Software Vault: The Gold Collection

home *** CD-ROM | disk | FTP | other *** search

/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr12 / pplasc.zip / PPL3.ASC < prev

Wrap

Text File | 1993-06-04 | 234KB | 6,630 lines

MODEM() Function Function Access the connect string as reported by the modem. Syntax MODEM() No arguments are required Return Type & Value STRING Returns the modem connect string. Remarks PCBoard expects and requires certain information to be reported by the modem anytime a user connects to the BBS. The minimum requirement is a string with the word CONNECT; other information may be included, such as the connect speed, error correction, data compression, etc. Should your PPL application have need of this information as well, it may be accessed with this function. Examples FAPPEND 1,"MODEM.LOG",O_WR,S_DW FPUTLN 1,LEFT(U_NAME(),30)+MODEM() FCLOSE 1 See Also MONEY Type Function Declare one or more variables of type money. Syntax MONEY var|arr(s[,s[,s]])[,var|arr(s[,s[,s]])] var The name of a variable to declare. Must start with a letter [A-Z] which may be followed by letters, digits [0-9] or the underscore [_]. May be of any length but only the first 32 characters are used. arr The name of an array variable to declare. The same naming conventions as var are used. s The size (0-based) of an array variable dimension. Any constant integer expression is allowed. Remarks MONEY variables are stored as positive or negative cents. The range of MONEY is $-21,474,836.48 through $+21,474,836.47. It is stored internally as a four byte signed long integer. If MONEY is assigned to or from an INTEGER type then the cents (- 2,147,483,648 - +2,147,483,647) are assigned. If MONEY is assigned to a STRING type then it is automatically converted to the following format: "$sD.CC", where s is the sign (- for negative amounts, nothing for positive amounts), D is the dollar amount (one or more digits as needed) and CC is the cents amount (00-99). If a STRING is assigned to MONEY then PPL will do it's best to convert the string back to the appropriate amount of money. All other types, when assigned to or from MONEY, will be converted to an INTEGER first before being assigned to or from the MONEY type. Examples MONEY itemAmt, subTot, total, priceList(2,17) See Also BOOLEAN Type, DATE Type, INTEGER Type, STRING Type, TIME Type MONTH() Function Function Extracts the month of the year from a specified date. Syntax MONTH(dexp) dexp Any date expression. Return Type & Value INTEGER Returns the month from the specified date expression (dexp). Valid return values are from 1 to 12. Remarks This function allows you to extract a particular piece of information about a DATE value, in this case the month of the date. Examples PRINTLN "This month is: ",MONTH(DATE()) See Also DAY() Function, DOW() Function, YEAR() Function MORE Statement Function Pause the display and ask the user how to continue. Syntax MORE No arguments are required Remarks It is often necessary to pause in the display of information and wait for the user to catch up. This statement allows you prompt the user on how to continue. The acceptable responses are Y (or whatever letter is appropriate for the users language selection) to continue, N (or, again, whatever letter is appropriate) to abort, or NS to continue in non-stop mode. It displays prompt number 196 from the PCBTEXT file for the current language to let the user know what is expected. Examples PRINTLN "Your account has expired!" PRINTLN "You are about to be logged off" MORE PRINTLN "Call me voice to renew your subscription" See Also WAIT Statement MPRINT/MPRINTLN Statements Function Print (write) a line to the caller's screen (modem) only (with an optional newline appended). Syntax M P R I N Te x p [ , e x p ] - o r - MPRINTLN [exp[,exp]] exp An expression of any type to evaluate and write to the caller's screen. Remarks These statements will evalutate zero, one or more expressions of any type and write the results to the modem for the caller's display. The MPRINTLN statement will append a newline to the end of the expressions; MPRINT will not. Note that at least one expression must be specified for MPRINT, unlike the MPRINTLN statement which need not have any arguments passed to it. These statements only send information to the modem and do not interpret @ codes; if the remote caller has ANSI then ANSI will be interpreted. Examples MPRINT "The name of the currently running PPE file is " MPRINTLN PPENAME(),"." MPRINT "The path where it is located is " MPRINTLN PPEPATH(),"." MPRINT "The date is ",DATE()," and the time is ",TIME(),"." MPRINTLN See Also PRINT/PRINTLN Statements, SPRINT/SPRINTLN Statements NC Constant Function To re-start the display of information according to the current mode. Value 0 = 0b = 0o = 0h Remarks The STARTDISP statement takes a single argument to start displaying information in a certain format. FCL tells PCBoard to count lines and pause as needed during the display of information. FNS tells PCBoard to not stop during the display of information. NC instructs PCBoard to start over with the last specified mode (FCL or FNS). Examples INTEGER i,j STARTDISP FCL FOR i = 1 TO 5 STARTDISP NC FOR j = 1 to 50 PRINTLN "This is line ",j NEXT NEXT See Also FCL Constant, FNS Constant NEWLINE Constant Function Set the new line after prompt flag in an INPUTSTR, PROMPTSTR, or DISPTEXT statement. Value 64 = 1000000b = 100o = 40h Remarks The INPUTSTR, PROMPTSTR, and DISPTEXT statements have the ability to send a carriage return/line feed after a prompt is displayed automatically and without the need to make a separate call to the NEWLINE statement. Examples STRING pwd INPUTSTR "Enter id",pwd,@X0E,4,"0123456789",LFBEFORE+NEWLINE+LFAFTE R IF (pwd <> "1234") PRINTLN "Bad id" See Also DISPTEXT Statement, INPUTSTR Statement, LFAFTER Constant, LFBEFORE Constant, PROMPTSTR Statement NEWLINE Statement Function Move the cursor to the beginning of the next line. Syntax NEWLINE No arguments are required Remarks This statement should be used for moving to the beginning of the next line on screen, scrolling if necessary. It will do so regardless of the current cursor position, unlike the FRESHLINE statement. Examples INTEGER i, end LET end = RANDOM(20) FOR i = 1 TO end PRINT RIGHT(RANDOM(10000),8) NEXT FRESHLINE NEWLINE PRINTLN "Now we continue with a blank line between" See Also FRESHLINE Statement, NEWLINES Statement NEWLINES Statement Function Execute a specified number of NEWLINE statements. Syntax NEWLINES count count An integer expression with the number of times to execute NEWLINE. Remarks This statement is convienient when executing multiple and/or variable NEWLINE statements for screen formatting. It takes a single integer expression argument and automatically executes that many NEWLINE statements for you without the need to set up a loop or to write multiple NEWLINE lines in your source code. Examples INTEGER i, end LET end = RANDOM(20) FOR i = 1 TO end PRINT RIGHT(RANDOM(10000),8) NEXT FRESHLINE NEWLINE 5 PRINTLN "Now we continue with a 5 blank lines between" See Also FRESHLINE Statement, NEWLINE Statement NEWPWD Statement Function Change the users password and maintain the password PSA if installed. Syntax NEWPWD pwd,var pwd A string expression with the new password for the user. var A variable to hold the password change status; TRUE if the password was changed or FALSE otherwise. Remarks There are two ways to change the users password under PPL control. The first is to simply use the GETUSER statement, assign the new password to the U_PWD variable, then issue the PUTUSER statement. However, this isn't adequate if the SysOp has installed the password PSA. This statement will take care of validating the password, checking it against the password history, updating the password history, setting a new expiration date if necessary and incrementing the times changed counter. If the password fails a validity test then this statement will set the var parameter to FALSE to let you know that the password wasn't changed. If the password PSA isn't installed or if the password conforms to the PSA requirements, then var will be set to TRUE. Examples BOOLEAN changed STRING pwd INPUTSTR "Enter a new password",pwd,@X0E,12,MASK_PWD(),ECHODOTS NEWLINE NEWPWD pwd,changed IF (!changed) PRINTLN "Password not changed" See Also NOCHAR() Function Function Get the no response character for the current language. Syntax NOCHAR() No arguments are required Return Type & Value STRING Returns the no character for the current language. Remarks Support for foreign language yes/no responses can be easily added by using this function to determine what a negative response should be instead of hardcoding the english "N" character. Examples STRING ans LET ans = YESCHAR() INPUTSTR "Run program now",ans,@X0E,1,"",AUTO+YESNO IF (ans = NOCHAR()) END See Also YESCHAR() Function, YESNO Constant NOCLEAR Constant Function Set the no clear input field flag in an INPUTSTR or PROMPTSTR statement. Value 1024 = 10000000000b = 2000o = 400h Remarks The INPUTSTR and PROMPTSTR statements have the ability to automatically clear the default value from the input field when the users presses his first key if ANSI is available. This is the default mode of operations. If you don't want this to happen, you may use this flag to disable this feature. Examples STRING cmds LET cmds = "QUIT" INPUTSTR "Commands",cmds,@X0E,60,MASK_ASCII(),STACKED+NOCLEA R TOKENIZE cmds LET cmds = GETTOKEN() IF (cmds = "QUIT") END KBDSTUFF cmds+TOKENSTR() See Also INPUTSTR Statement, PROMPTSTR Statement NOT() Function Function Calculate the bitwise NOT of an integer argument. Syntax NOT(iexp) iexp Any integer expression. Return Type & Value INTEGER Returns the bitwise NOT of iexp. Remarks This function may be used to toggle all bits in an integer expression. Wherever a bit had been set it will be clear after this function call, and vice versa. Examples ' Toggle the bits PRINTLN NOT(1248h) ' Toggle all flag INTEGER flag LET flag = NOT(flag) See Also AND() Function, OR() Function, XOR() Function ONLOCAL() Function Function Determine whether or not a caller is on locally. Syntax ONLOCAL() No arguments are required Return Type & Value BOOLEAN Returns TRUE if the caller is on locally, FALSE otherwise. Remarks There are some features that work differently for local and remote callers, such as file transfers and modem communications. This function will report to you whether or not a user is logged on locally and allow you to handle local processing differently than remote processing. Examples IF (ONLOCAL()) THEN PRINTLN "Call back verification cannot be performed for" PRINTLN "users logged in locally!" END ENDIF CALL "CALLBACK.PPE" See Also OPENCAP Statement Function Open the screen capture file. Syntax OPENCAP file,stat file A string expression with the filename to open. stat A variable to hold the return status (TRUE if error opening file, FALSE otherwise). Remarks PCBoard has the ability to capture screen output to a file for later reference. PPL allows that same ability via the OPENCAP and CLOSECAP statements. This could be useful in a program that executes a series of commands in non-stop mode. The process could open a capture file first, execute the commands, close the capture file, then allow the user to view or download the capture file. CLOSECAP closes the capture file and turns off screen capturing. Also, the SHOWON and SHOWOFF statements can be used to turn on and off showing information to the screen while allowing that same information (even if not displayed or transmitted via modem) to be captured to a file. The SHOWSTAT() function can be used to check the current status of the SHOWON and SHOWOFF statements. Examples BOOLEAN ss LET ss = SHOWSTAT() SHOWOFF OPENCAP "CAP"+STRING(PCBNODE()),ocFlag IF (ocFlag) THEN DIR "U;NS" CLOSECAP KBDSTUFF "FLAG CAP"+STRING(PCBNODE())+CHR(13) ENDIF IF (ss) THEN SHOWON ELSE SHOWOFF ENDIF See Also CLOSECAP Statement, SHOWOFF Statement, SHOWON Statement, SHOWSTAT() Function OPTEXT Statement Function Set the text to be used by the @OPTEXT@ macro. Syntax OPTEXT str str Any string expression. Remarks The @OPTEXT@ macro is used to include operation specific text in prompts and display files. Normally PCBoard automatically fills it in with the appropriate value. However, you can use it for your own purposes by issuing this statement to set the text and immediately displaying the information that should use it (by either printing a line or displaying a file). Examples OPTEXT STRING(DATE())+" & "+STRING(TIME()) PRINTLN "The date and time are @OPTEXT@" DISPFILE "FILE",GRAPH+SEC+LANG See Also OR() Function Function Calculate the bitwise OR of two integer arguments. Syntax OR(iexp1,iexp2) iexp1 Any integer expression. iexp2 Any integer expression. Return Type & Value INTEGER Returns the bitwise OR of iexp1 and iexp2. Remarks This function may be used to set selected bits in an integer expression by ORing the expression with a mask that has the bits to set set to 1 and the bits to ignore set to 0. Examples ' Set the bits in the low byte PRINTLN OR(1248h,00FFh) ' Randomly set a flag the hard way INTEGER flag LET flag = OR(RANDOM(1),RANDOM(1)) See Also AND() Function, NOT() Function, XOR() Function O_RD Constant Function Set the open for read access flag in a FCREATE/FOPEN/FAPPEND statement. Value 0 = 0b = 0o = 0h Remarks Files may be opened for read, write or combined read/write access. You should only use the access you need to allow other processes to open files at the same time in multitasking and networked environments. This constant will allow your PPE to read from a file without writing any information out to it. Examples FOPEN 1,"FILE.DAT",O_RD,S_DN ' Open for read access FOR i = 1 TO 10 FGET 1,s PRINTLN s NEXT FCLOSE 1 See Also O_RW Constant, O_WR Constant O_RW Constant Function Set the open for read and write access flag in a FCREATE/FOPEN/FAPPEND statement. Value 2 = 10b = 2o = 2h Remarks Files may be opened for read, write or combined read/write access. You should only use the access you need to allow other processes to open files at the same time in multitasking and networked environments. This constant will allow your PPE to both read from and write to a file without the need to close and reopen it between accesses. Examples FOPEN 1,"FILE.DAT",O_RW,S_DN ' Open for read and write access FOR i = 1 TO 10 FPUT 1,"X" FGET 1,s PRINTLN s NEXT FCLOSE 1 See Also O_RD Constant, O_WR Constant O_WR Constant Function Set the open for write access flag in a FCREATE/FOPEN/FAPPEND statement. Value 1 = 1b = 1o = 1h Remarks Files may be opened for read, write or combined read/write access. You should only use the access you need to allow other processes to open files at the same time in multitasking and networked environments. This constant will allow your PPE to write to a file but will restrict read access. Examples FOPEN 1,"FILE.DAT",O_WR,S_DN ' Open for write access FOR i = 1 TO 10 FPUTLN 1,"Line ",i NEXT FCLOSE 1 See Also O_RD Constant, O_RW Constant PAGEOFF Statement Function Turn off the SysOp paged indicator. Syntax PAGEOFF No arguments are required Remarks One of the features of PCBoard where change is often requested is the operator page facility. Some people want to be able to configure multiple ranges of availability per day, some want a different sounding page bell, longer or shorter page attempts, etc, etc. This statement, along with the CHAT and PAGEON statements and the PAGESTAT() function, allow you to implement an operator page in any way desired. Examples PAGEON FOR i = 1 TO 10 PRINT "@BEEP@" DELAY 18 IF (KINKEY() = " ") THEN PAGEOFF SHELL TRUE,i,"SUPERCHT","" GOTO exit ENDIF NEXT :exit See Also CHAT Statement, PAGEON Statement, PAGESTAT() Function PAGEON Statement Function Turn on the SysOp paged indicator and update user statistics. Syntax PAGEON No arguments are required Remarks One of the features of PCBoard where change is often requested is the operator page facility. Some people want to be able to configure multiple ranges of availability per day, some want a different sounding page bell, longer or shorter page attempts, etc, etc. This statement, along with the CHAT and PAGEOFF statements and the PAGESTAT() function, allow you to implement an operator page in any way desired. Note that this statement will also update the current callers statistics PSA if it is installed. Examples PAGEON FOR i = 1 TO 10 PRINT "@BEEP@" DELAY 18 IF (KINKEY() = " ") THEN CHAT GOTO exit ENDIF NEXT :exit See Also CHAT Statement, PAGEOFF Statement, PAGESTAT() Function PAGESTAT() Function Function Determine if the current user has paged the SysOp. Syntax PAGESTAT() No arguments are required Return Type and Value BOOLEAN Returns TRUE if the user has paged the SysOp, FALSE otherwise. Remarks One of the features of PCBoard where change is often requested is the operator page facility. Some people want to be able to configure multiple ranges of availability per day, some want a different sounding page bell, longer or shorter page attempts, etc, etc. This function, along with the CHAT, PAGEON and PAGEOFF statements, allow you to implement an operator page in any way desired. Examples IF (PAGESTAT()) THEN PRINTLN "You have already paged the SysOp," PRINTLN "please be patient." ELSE PAGEON PRINTLN "The SysOp has been paged, continue" ENDIF See Also CHAT Statement, PAGEOFF Statement, PAGEON Statement PCBDAT() Function Function Return the path and file name of the PCBOARD.DAT file. Syntax PCBDAT() No arguments are required Return Type & Value STRING Returns the path and file name of the PCBOARD.DAT file for the currnet node. Remarks The PCBOARD.DAT file is the master confiuration file for each node running PCBoard. As such, there are many useful pieces of information that can be obtained from it. It is a standard text file with one piece of information per line. You may use the READLINE() function to read individual pieces of information from it. Examples STRING s LET s = READLINE(PCBDAT(),1) PRINTLN "PCBOARD.DAT version info - ",s See Also PCBNODE() Function Function Return the current node number. Syntax PCBNODE() No arguments are required Return Type & Value INTEGER Returns the node number for the current node. Remarks You may have need to know what node is in use for certain applications (for example, to create temporary files with unique names or to restrict features to a particular node or nodes). This function will return a number from 1 to the maximum number of nodes allowed with a given copy of PCBoard. Note that the node number may not be what is defined in PCBOARD.DAT if the /FLOAT or /NODE switches are used. Examples STRING file LET file = "TMP"+STRING(PCBNODE())+".$$$" DELETE file See Also PEEKB() Function Function Return the value of a byte at a specified memory address. Syntax PEEKB(addr) addr An integer expression with the address of the byte to peek. Return Type & Value INTEGER Returns the value of the byte at addr. Remarks It is sometimes necessary to read values from memory directly (for example, from the system BIOS data segment). This function will return a byte quantity (0-255) from a specified memory address. Examples PRINTLN "The current video mode is ",PEEKB(MKADDR(40h,49h)) See Also MKADDR() Function, PEEKDW() Function, PEEKW() Function, POKEB() Function, POKEDW() Function, POKEW() Function, VARADDR Statement, VAROFF Statement, VARSEG Statement PEEKDW() Function Function Return the value of a double word at a specified memory address. Syntax PEEKDW(addr) addr An integer expression with the address of the double word to peek. Return Type & Value INTEGER Returns the value of the double word at addr. Remarks It is sometimes necessary to read values from memory directly (for example, from the system BIOS data segment). This function will return a double word quantity as a signed integer (- 2,147,483,648 - +2,147,483,647) from a specified memory address. Examples PRINTLN "Timer ticks since midnight = ",PEEKDW(MKADDR(40h,6Ch)) See Also MKADDR() Function, PEEKB() Function, PEEKW() Function, POKEB() Function, POKEDW() Function, POKEW() Function, VARADDR Statement, VAROFF Statement, VARSEG Statement PEEKW() Function Function Return the value of a word at a specified memory address. Syntax PEEKW(addr) addr An integer expression with the address of the word to peek. Return Type & Value INTEGER Returns the value of the word at addr. Remarks It is sometimes necessary to read values from memory directly (for example, from the system BIOS data segment). This function will return a word quantity (0-65,535) from a specified memory address. Examples PRINTLN "The usable memory size is ",PEEKW(MKADDR(40h,13h)) See Also MKADDR() Function, PEEKB() Function, PEEKDW() Function, POKEB() Function, POKEDW() Function, POKEW() Function, VARADDR Statement, VAROFF Statement, VARSEG Statement POKEB Statement Function Write a byte to a specified memory address. Syntax POKEB addr,value addr An integer expression with the address to write to. value An integer expression with the value to write to addr. Remarks You may have need to write directly to memory from time to time. This statement complements the PEEKB() function and allows you to write a byte value (0-255) to a specific memory location. Examples BOOLEAN flag INTEGER addr VARADDR flag,addr POKEB addr,TRUE ' Set the flag to TRUE the hard way See Also MKADDR() Function, PEEKB() Function, PEEKDW() Function, PEEKW() Function, POKEDW() Function, POKEW() Function, VARADDR Statement, VAROFF Statement, VARSEG Statement POKEDW Statement Function Write a double word to a specified memory address. Syntax POKEDW addr,value addr An integer expression with the address to write to. value An integer expression with the value to write to addr. Remarks You may have need to write directly to memory from time to time. This statement complements the PEEKDW() function and allows you to write a double word value (-2,147,483,648 - +2,147,483,647) to a specific memory location. Examples MONEY amt INTEGER addr VARADDR amt,addr POKEDW addr,123456 ' Set amt to $1234.56 the hard way See Also MKADDR() Function, PEEKB() Function, PEEKDW() Function, PEEKW() Function, POKEB() Function, POKEW() Function, VARADDR Statement, VAROFF Statement, VARSEG Statement POKEW Statement Function Write a word to a specified memory address. Syntax POKEW addr,value addr An integer expression with the address to write to. value An integer expression with the value to write to addr. Remarks You may have need to write directly to memory from time to time. This statement complements the PEEKW() function and allows you to write a word value (0-65,535) to a specific memory location. Examples DATE dob INTEGER addr VARADDR dob,addr POKEW addr,MKDATE(1967,10,31) ' Set dob the hard way See Also MKADDR() Function, PEEKB() Function, PEEKDW() Function, PEEKW() Function, POKEB() Function, POKEDW() Function, VARADDR Statement, VAROFF Statement, VARSEG Statement POP Statement Function Pop the results of one or more expressions from a stack. Syntax POP var[,var] var A variable of any type in which to retrieve previously pushed expression. Remarks This statement will retrieve the results of one or more expressions of any type from a stack into a list of variables. The values should have been previously pushed with the PUSH statement. Together PUSH and POP can be used for parameter passing, to create 'local' variables, or to reverse the order of arguments. Examples INTEGER i, tc STRING s LET tc = TOKCOUNT() WHILE (TOKCOUNT() > 0) PUSH GETTOKEN() ' push them in order FOR i = 1 TO tc POP s ' pop them in reverse PRINTLN s NEXT INTEGER i FOR i = 1 TO 10 PRINT i," - " GOSUB sub NEXT END :sub PUSH i ' temporarily save i LET i = i*i PRINTLN i POP i ' restore saved i RETURN INTEGER v PRINT "A cube with dimensions 2X3X4" PUSH 2,3,4 ' pass pushed parameters GOSUB vol POP v ' pop result PRINTLN "has volume ",v END :vol INTEGER w,h,d POP d,h,w ' pop passed parameter PUSH w*h*d ' push result RETURN See Also PUSH Statement PPENAME() Function Function Return the base name of an executing PPE file. Syntax PPENAME() No arguments are required Return Type & Value STRING Returns the base file name (without path or extension) of the currently executing PPE. Remarks This function will return the name of the PPE file that is running. This can be useful when writing PPL applications that will use data files that you would like to keep named the same as the parent application regardless of what the PPE name may change to. Examples STRING s FOPEN 1,PPEPATH()+PPENAME()+".CFG",O_RD,S_DN FGET 1,s FCLOSE 1 See Also PPEPATH() Function PPEPATH() Function Function Return the path of an executing PPE file. Syntax PPEPATH() No arguments are required Return Type & Value STRING Returns the path (without file name or extension) of the currently executing PPE. Remarks This function will return the path of the PPE file that is running. This can be useful when writing PPL applications that will use files that you would like to keep in the same location as the parent application regardless of where the PPE may be installed. Examples STRING s FOPEN 1,PPEPATH()+PPENAME()+".CFG",O_RD,S_DN FGET 1,s FCLOSE 1 See Also PPENAME() Function PRINT/PRINTLN Statements Function Print (write) a line to the screen (with an optional newline appended). Syntax P R I N T e x p [ , e x p ] - o r - PRINTLN [exp[,exp]] exp An expression of any type to evaluate and write to the screen. Remarks These statements will evalutate zero, one or more expressions of any type and write the results to the display. The PRINTLN statement will append a newline to the end of the expressions; PRINT will not. Note that at least one expression must be specified for PRINT, unlike the PRINTLN statement which need not have any arguments passed to it. Finally, both statements will process all @ codes and display them as expected. Examples PRINT "The name of the currently running PPE file is " PRINTLN PPENAME(),"." PRINT "The path where it is located is " PRINTLN PPEPATH(),"." PRINT "The date is ",DATE()," and the time is ",TIME(),"." PRINTLN PRINT "@X1FThis is bright white on blue..." PRINTLN "how do you like it @FIRST@" See Also MPRINT/MPRINTLN Statements, SPRINT/SPRINTLN Statements PROMPTSTR Statement Function Prompt the user for a string of text in a specific format. Syntax PROMPTSTR prompt,var,len,valid,flags prompt An integer expression with the prompt number from PCBTEXT to display to the user. var The variable in which to store the user's input. len An integer expression with maximum length of text to input. valid A string expression with the valid characters that the user may enter. flags An integer expression with flags to modify how the statement works. Remarks This statement will accept a string of input from the user, up to the length defined. The prompt parameter will be used to find the prompt from PCBTEXT (which includes the prompt color) to display to the user. Only characters found in the valid parameter will be accepted. However, the flags parameter may affect how prompt is displayed and the valid characters that are accepted. Individual flags may be added together as needed. Several functions exist to easily specify commonly used valid character masks. They are MASK_ALNUM(), MASK_ALPHA(), MASK_ASCII(), MASK_FILE(), MASK_NUM(), MASK_PATH(), and MASK_PWD(). Defined flag values are AUTO, DEFS, ECHODOTS, ERASELINE, FIELDLEN, GUIDE, HIGHASCII, LFAFTER, LFBEFORE, NEWLINE, NOCLEAR, STACKED, UPCASE, WORDWRAP, and YESNO. Examples BOOLEAN b DATE d INTEGER i MONEY m STRING s TIME t ' NOTE: prompt 706 is used here for all statements; ' you may use any prompt you wish PROMPTSTR 706,b,1,"10",LFBEFORE+NEWLINE PROMPTSTR 706,d,8,"0123456789-",NEWLINE+NOCLEAR PROMPTSTR 706,i,20,MASK_NUM(),NEWLINE PROMPTSTR 706,m,9,MASK_NUM()+".",NEWLINE+DEFS+FIELDLEN PROMPTSTR 706,s,63,MASK_ASCII(),NEWLINE+FIELDLEN+GUIDE PROMPTSTR 706,t,5,"0123456789"+":",NEWLINE+LFAFTER PRINTLN b," ",d," ",i PRINTLN m," ",s," ",t See Also INPUT Statement, INPUT... Statement, INPUTSTR Statement, INPUTTEXT Statement PSA() Function Function Determine whether or not a given PSA is installed. Syntax PSA(num) num An integer expression with the number of the PSA to check for the existence of. Return Type & Value BOOLEAN Returns TRUE if the specified PSA exists or FALSE if it doesn't exist for the following values of num: 1 The Alias PSA; 2 The Verification PSA. 3 The Address PSA; 4 The Password PSA; 5 The Statistics PSA. 6 The Notes PSA. Remarks This function allows you to determine whether or not a given PCBoard Supported Allocation (PSA) is installed. For each of the six PSAs it will return TRUE if installed or FALSE if not installed. It is useful when you want to write a generic PPL application that will access one or more PSAs that may or may not be installed. Examples STRING ynStr(1) LET ynStr(0) = "NO" LET ynStr(1) = "YES" PRINTLN " Alias Support Enabled? ",ynStr(PSA(1)) PRINTLN "Verification Support Enabled? ",ynStr(PSA(2)) PRINTLN " Address Support Enabled? ",ynStr(PSA(3)) PRINTLN " Password Support Enabled? ",ynStr(PSA(4)) PRINTLN " Statistics Support Enabled? ",ynStr(PSA(5)) PRINTLN " Notes Support Enabled? ",ynStr(PSA(6)) See Also PUSH Statement Function Push (save) the results of one or more expressions on a stack. Syntax PUSH exp[,exp] exp An expression of any type to evaluate and push. Remarks This statement will evalutate one or more expressions of any type and push the results onto a stack for temporary storage. The results of those expressions may be retrieved via the POP statement. Together PUSH and POP can be used for parameter passing, to create 'local' variables, or to reverse the order of arguments. Examples INTEGER i, tc STRING s LET tc = TOKCOUNT() WHILE (TOKCOUNT() > 0) PUSH GETTOKEN() ' push them in order FOR i = 1 TO tc POP s ' pop them in reverse PRINTLN s NEXT INTEGER i FOR i = 1 TO 10 PRINT i," - " GOSUB sub NEXT END :sub PUSH i ' temporarily save i LET i = i*i PRINTLN i POP i ' restore saved i RETURN INTEGER v PRINT "A cube with dimensions 2X3X4" PUSH 2,3,4 ' pass pushed parameters GOSUB vol POP v ' pop result PRINTLN "has volume ",v END :vol INTEGER w,h,d POP d,h,w ' pop passed parameter PUSH w*h*d ' push result RETURN See Also POP Statement PUTUSER Statement Function Copy values from predeclared variables to user record. Syntax PUTUSER No arguments are required Remarks There are many predeclared variables which may be used to access and change user information. However, their values are undefined until you use the GETUSER statement, and any changes you make don't take hold until you use the PUTUSER statement. Examples IF (PSA(3)) THEN GETUSER INPUT "Addr 1",U_ADDR(0) INPUT "Addr 2",U_ADDR(1) INPUT "City ",U_ADDR(2) INPUT "State ",U_ADDR(3) INPUT "ZIP ",U_ADDR(4) INPUT "Cntry ",U_ADDR(5) PUTUSER ENDIF See Also GETUSER Statement QUEST Statement Function Allow the user to answer a specified script questionnaire. Syntax QUEST scrnum scrnum The number of the script for the user to answer. Valid values are 1 through the number of script questionnaires available. Remarks This statement will present the user a specified script questionnaire number to answer. The SCR.LST file for the current conference will be searched for the script. If the questionnaire number is invalid (less than 1 or greater than the highest script number defined) then nothing will be displayed. Examples INTEGER num INPUT "Script to answer",num QUEST num See Also RANDOM() Function Function Return a random value between 0 and a specified limit. Syntax RANDOM(limit) limit An integer expression with the maximum random value desired. Return Type & Value INTEGER Returns the random number in the range 0 to limit. Remarks Random numbers have many applications from statistics to video games. This function allows you to generate pseudo-random numbers in the range 0 to limit inclusive. Examples INTEGER x,y WHILE (KINKEY() <> " ") DO CLS LET x = 1+RANDOM(50) LET y = 1+RANDOM(22) COLOR 1+RANDOM(14) ANSIPOS x,y PRINT "Hit the SPACE BAR to continue" DELAY 18 ANSIPOS x,y CLREOL ENDWHILE See Also RDUNET Statement Function Read information from the USERNET file for a specific node. Syntax RDUNET node node An integer expression with the node to read. Remarks To facilitate internode communications, a file named USERNET.XXX is maintained with an entry for each node on the system. This file is used by the BROADCAST command of PCBoard and to prevent multiple simultaneous logins, among other things. This statement may be used to read information for any node. Examples RDUNET PCBNODE() WRUNET PCBNODE(),UN_STAT(),UN_NAME(),UN_CITY(),"Running "+PPENAME(),"" RDUNET 1 WRUNET 1,UN_STAT(),UN_NAME(),UN_CITY(),UN_OPER(),"Hello there node 1" See Also UN_...() Function, RDUNET Statement RDUSYS Statement Function Read a USERS.SYS file in from disk. Syntax RDUSYS No arguments are required Remarks Some DOOR applications require a USERS.SYS file to access information about the caller. This statement allows you to read the USERS.SYS file back into memory in case any changes were made by the DOOR during the SHELL statement. This statement should only be used after a SHELL statement that was preceeded by a WRUSYS statement. Examples INTEGER ret WRUSYS SHELL FALSE,ret,"MYAPP.EXE","" RDUSYS See Also WRUSYS Statement READLINE() Function Function Read a specific line number from a text file. Syntax READLINE(file,line) file A string expression with the file name to read from. line An integer expression with the line number to read. Return Type & Value STRING Returns the specified line number from file. Remarks It is often convienient to read a specified line number from a file without going to all the overhead of opening, reading and closing. This function will open the file in read mode for share deny none access and quickly read up to the line number you specify. If the line you want doesn't exist an empty string will be returned. Additionally, this function will remember the last file and line read so that it may quickly continue where it left off if you try to read a number of lines sequentially from the same file. Finally, the last file specified will remain open until the PPE exits and returns control to PCBoard. Examples PRINTLN "This system is running on IRQ ",READLINE(PCBDAT(),158) PRINTLN "with a base IO address of ",READLINE(PCBDAT(),159) See Also REG...() Functions Function Get the value of a register. Syntax REG...() No arguments are required REG should be followed by one of the following register names: AH, AL, AX, BH, BL, BX, CF, CH, CL, CX, DH, DI, DL, DS, DX, ES, F or SI. Return Type & Value BOOLEAN (REGCF() only) Returns TRUE if the carry flag is set, FALSE otherwise. INTEGER (All others) Returns the value in the specified register. Remarks There are actually 18 different functions that return the values of registers. AL, AH, BL, BH, CL, CH, DL, and DH will always return byte sized values (0-255). AX, BX, CX, DX, DI, SI, DS, and ES will always return word sized values (0-65535). F (flags) returns the settings for the various 80x86 processor flags. CF is a subset of F in that it only returns the status of the carry flag. It exists because the carry flag is often used to report success or failure in assembly language. The REGF() function returns the settings for the following flags: Carry, Parity, Auxilliary, Zero, Sign, Trap, Interrupt, Direction, and Overflow. Their bit positions are as follows: O D I T S Z - A - P - C 80 40 20 10 08 04 02 01 00 00 00 00 0h 0h 0h 0h 0h 0h 0h 0h 8h 4h 2h 1h Examples ' Create subdirectory - DOS function 39h INTEGER addr STRING path LET path = "C:\$TMPDIR$" VARADDR path,addr DOINTR 21h,39h,0,0,addr%00010000h,0,0,0,addr/00010000h,0 IF (REGCF() & (REGAX() = 3)) THEN PRINTLN "Error: Path not found" ELSE IF (REGCF() & (REGAX() = 5)) THEN PRINTLN "Error: Access Denied" ELSE IF (REGCF()) THEN PRINTLN "Error: Unknown Error" ELSE PRINTLN "Directory successfully created..." ENDIF See Also B2W() Function, DOINTR Statement, VARADDR Statement, VAROFF Statement, VARSEG Statement RENAME Statement Function Rename (or move) a file. Syntax RENAME old,new old A string expression with the old path and/or file name. new A string expression with the new path and/or file name. Remarks Similar to how the RENAME command works from the DOS prompt, this statement will take a file and give it a new name. Unlike the RENAME command, the RENAME statement will not accept wildcards in the old or new parameters. Also, it doesn't require that the old path and the new path be the same (the drive letters must match, but the paths need not), so it may be used to move files from one location to another on a single drive. So, you could use it to move a file from C:\PCB\NODE1 to C:\PCB\NODE2 (renaming it at the same time if you wish), but you couldn't use it to move a file from C:\PCB\NODE1 to D:\WORK\NODE1. Examples ' Swap the PCBOARD DAT & NXT files RENAME "PCBOARD.DAT","PCBOARD.TMP" RENAME "PCBOARD.NXT","PCBOARD.DAT" RENAME "PCBOARD.TMP","PCBOARD.NXT" ' Move the file to the backup directory RENAME "PPE.LOG","LOGBAK\"+I2S(DATE()*86400+TIME(),36) See Also REPLACE() Function Function Change all occurences of a given character to another character in a string. Syntax REPLACE(str,old,new) str Any string expression. old A string expression with the old character to be replaced. new A string expression with the new character to replace with. Return Type & Value STRING Returns str with all occurences of old changed to new. Remarks This function will search a string for a given character and replace all instances of that character with another character. This can be useful in many scenarios, especially when formatting text for display purposes. Examples PRINTLN "Your internet address on this system is:" PRINTLN REPLACE(LOWER(U_NAME())," ","."),"@clarkdev.com" See Also RESETDISP Statement Function Reset the display to allow more information after an abort. Syntax RESETDISP No arguments are required Remarks PCBoard normally automatically counts lines and, if enabled, pauses the display after every screenful. The user may (unless disabled) abort the display at any MORE? prompt or with the ^K/^X keys. If this happens no further information will be displayed until you use the RESETDISP statement. You can check to see if RESETDISP is necessary (ie, has the user aborted the display) with the ABORT() function. Examples INTEGER I STARTDISP FCL ' While the user has not aborted, continue WHILE (!ABORT()) DO PRINTLN "I is equal to ",I INC I ENDWHILE RESETDISP See Also ABORT() Function, STARTDISP Statement RESTSCRN Statement Function Restore the screen from a previously saved buffer. Syntax RESTSCRN No arguments are required Remark PCBoard will save and restore the screen before and after certain functions, such as SysOp chat. This allows the user to continue right where he left off without having to remember what was on the screen before being interrupted. You can add that same functionality with the SAVESCRN and RESTSCRN statements. The SAVESCRN statement allocates memory for a buffer in which to save the screen. If the SAVESCRN statement isn't followed by a RESTSCRN statement then that memory will never be deallocated. Finally, this statement will work regardless of ANSI availability; the screen is only saved up to the position of the cursor and this statement assumes that it can safely restore the screen using standard teletype conventions to just scroll the data onto the display. Examples SAVESCRN CLS PRINTLN "We interrupt your regular BBS session" PRINTLN "with this important message:" NEWLINE PRINTLN "A subscription to this system only costs $5!" PRINTLN "Subscribe today!" NEWLINES 2 WAIT RESTSCRN See Also SAVESCRN Statement RETURN Statement Function Transfer program control back to a previously saved address. Syntax RETURN No arguments are required Remarks It is often necessary to perform an indentical set of instructions several times in a program. This leaves you with two choices. One, rewrite the code several times (and hope you do it right each time), or two, write it once as a subroutine, then use GOSUB to run it. This statement will save the address of the next line so that a RETURN statement at the end of the subroutine can instruct PPL to resume execution with the line following the GOSUB. Examples STRING Question, Answer LET Question = "What is your street address ..." GOSUB ask LET Question = "What is your city, state and zip ..." GOSUB ask END :ask ' Sub to ask a question, get an answer, and log them to a file LET Answer = "" PRINTLN "@X0E",Question INPUT "",Answer NEWLINES 2 FPUTLN 0,"Q: ",STRIPATX(Question) FPUTLN 0,"A: ",Answer RETURN See Also END Statement, GOSUB Statement, GOTO Statement, STOP Statement RIGHT() Function Function Access the right most characters from a string. Syntax RIGHT(str,chars) str A string expression to take the right most characters of. chars An integer expression with the number of characters to take from the right end of str. Return Type & Value STRING Returns a string with the right most chars characters of str. Remarks This function will return a sub string with the right most chars characters of a specified string. This can be useful in data processing as well as text formatting. If chars is less than or equal to 0 then the returned string will be empty. If chars is greater than the length of str then the returned string will have spaces added to the right to pad it out to the full length specified. Examples WHILE (RANDOM(250) <> 0) PRINT RIGHT(RANDOM(250),4)," " STRING s FOPEN 1,"DATA.TXT",O_RD,S_DN WHILE (!FERR(1)) DO FGET 1,s PRINT RTRIM(LEFT(s,25)," ")," - " PRINTLN RIGHT(s,LEN(s)-25) ENDWHILE FCLOSE 1 See Also LEFT() Function, MID() Function RTRIM() Function Function Trim a specified character from the right end of a string. Syntax RTRIM(str,ch) str Any string expression. ch A string with the character to strip from the right end of str. Return Type & Value STRING Returns the trimmed str. Remarks A common need in programming is to strip leading and/or trailing spaces (or other characters). This function will strip a specified character from the right end of a string and return the trimmed string. Examples STRING s LET s = " TEST " PRINTLN RTRIM(s," ") ' Will print " TEST" PRINTLN RTRIM(".....DA"+"TA.....",".") ' Will print ".....DATA" PRINTLN RTRIM(".....DA"+"TA....."," ") ' Will print ".....DATA....." See Also LTRIM() Function, TRIM() Function S2I() Function Function Convert a string in a specified number base to an integer. Syntax S2I(str,base) str Any string expression to convert to integer format. base An integer expression with the number base (2 through 36) to convert from. Return Type & Value INTEGER Returns str converted from the specified number base to an integer. Remarks People work with decimal (base 10) numbers, whereas computers work with binary (base 2) numbers. It is often more convienient to store or input numbers in a format other than decimal for clarity, compactness, or other reasons. This function will convert a string in any number base from 2 to 36 to a number. So, S2I("1010",2) would return a 10; S2I("Z",36) would return 35. For more information on number bases, consult . Examples INTEGER i STRING s INPUTTEXT "Enter a string (any base)",s,@X0E,40 FOR i = 2 TO 36 PRINTLN s," = ",S2I(s,i)," base ",i NEXT See Also I2S() Function SAVESCRN Statement Function Save the screen to a buffer for later restoration. Syntax SAVESCRN No arguments are required Remark PCBoard will save and restore the screen before and after certain functions, such as SysOp chat. This allows the user to continue right where he left off without having to remember what was on the screen before being interrupted. You can add that same functionality with the SAVESCRN and RESTSCRN statements. The SAVESCRN statement allocates memory for a buffer in which to save the screen. If the SAVESCRN statement isn't followed by a RESTSCRN statement then that memory will never be deallocated. Finally, this statement will work regardless of ANSI availability; this statement will only save the screen up to the position of the cursor. It is assumed that the screen can be safely restored using standard teletype conventions to just scroll the data onto the display. Examples SAVESCRN CLS PRINTLN "We interrupt your regular BBS session" PRINTLN "with this important message:" NEWLINE PRINTLN "A subscription to this system only costs $5!" PRINTLN "Subscribe today!" NEWLINES 2 WAIT RESTSCRN See Also RESTSCRN Statement SCRTEXT() Function Function Access text and attribute information directly from BBS screen memory. Syntax SCRTEXT(x,y,len,color) x An integer expression with the x coordinate (column) from which to read screen memory. y An integer expression with the y coordinate (row) from which to read screen memory. len An integer expression with the length, in columns, of the string to read from screen memory. color A boolean expression with TRUE if color information should be included, FALSE otherwise. Return Type & Value STRING Returns the specified region of screen memory. Remarks This function is useful for temporarily saving a portion of screen memory, with or without color information. If the color parameter is set to TRUE color information will be included in the form of @X codes embedded in the text. Note that the maximum length of a string is 256 characters; however, a row of 80 characters could be as long as 400 characters (4 bytes for the @X code and 1 byte for the character itself). You should generally limit yourself to a length of 51 characters or less if you want to include color information unless you are certain that attribute changes will not exceed the 256 character string limit. Examples ' scroll the screen to the left 5 columns and down 3 rows INTEGER r STRING s FOR r = 20 TO 1 STEP -1 LET s = SCRTEXT(6,r,75,TRUE) ANSIPOS 1,r+3 CLREOL PRINT s NEXT FOR r = 1 TO 3 ANSIPOS 1,r CLREOL NEXT See Also SEC Constant Function Set the security level specific file search flag in a DISPFILE statement. Value 2 = 10b = 2o = 2h Remarks The DISPFILE statement will allow you to display a file to the user, and optionally to have PCBoard look for alternate security, graphics, and/or language specific files. This flag instructs PCBoard to search for alternate security level files via the security level suffix. The current security level may be obtained with the CURSEC() function. Examples STRING s DISPFILE "MNUA",SEC+GRAPH+LANG INPUT "Option",s See Also CURSEC() Function, DISPFILE Statement, GRAPH Constant, LANG Constant SEC() Function Function Extract the second of the minute from a specified time of day. Syntax SEC(texp) texp Any time expression. Return Type & Value INTEGER Returns the second of the minute from the specified time expression (texp). Valid return values are from 0 to 59. Remarks This function allows you to extract a particular piece of information about a TIME value, in this case the second of the minute of the time of day expression. Examples PRINTLN "The minute is ",SEC(TIME()) See Also HOUR() Function, MIN() Function SENDMODEM Statement Function Send a string to the modem. Syntax SENDMODEM str str A string expression to send to the modem. Remarks The primary use of this statement is to send commands to a modem when no one is online. For example, you would use this to send a dial command to the modem in a call back PPL application. However, it is not restricted to sending commands. Note that modem commands must be terminated by a carriage return and that this statement will not automatically do it for you. This allows you to send a command to the modem is several stages and only terminate the final stage with a carriage return. Examples BOOLEAN flag CDCHKOFF KBDCHKOFF DTROFF DELAY 18 DTRON SENDMODEM "ATDT" SENDMODEM "5551212" SENDMODEM CHR(13) WAITFOR "CONNECT",flag,60 IF (!flag) LOG "No CONNECT after 60 seconds",FALSE KBDCHKON CDCHKON See Also SHELL Statement Function Shell out to a program or batch file. Syntax SHELL viacc,retcode,prog,cmds viacc A boolean expression with value TRUE if the shell should be made via COMMAND.COM; FALSE if it should be shelled to directly. retcode A variable in which to store the return code. prog A string expression with the file name to shell to. cmds A string expression with any arguments to pass to prog. Remarks You may have have need to run a COM, EXE or BAT file from your PPE. You may need to do this to simulate running a DOOR or to access some service not normally available from PCBoard or PPL. This function will allow you to do that. If the viacc parameter is TRUE (you want COMMAND.COM to load the specified file) then your PATH environment variable will be searched for prog if it isn't in the current directory or isn't fully qualified (path and extension) as though you had entered it on the command line. If viacc is FALSE then you must specify the path and extension of the program to run. Additionally, the retcode variable will only be meaningful if viacc is FALSE. Examples INTEGER rc SHELL TRUE,rc,"DOOR","" INTEGER rc STRING p,c LET p = "DOORWAY.EXE" LET c = "com2 /v:d^O /m:600 /g:on /o: /k:v0 /x: /c:dos" SHELL FALSE,rc,p,c See Also SHOWOFF Statement Function Turn off showing information to the display. Syntax SHOWOFF No arguments are required Remark This statement allows your PPL application to turn off writing information to the local and remote displays. Used in conjunction with the SHOWSTAT() function and the OPENCAP, CLOSECAP, and SHOWON statements it allows you to temporarily turn off the display while capturing output to the screen. This can be useful anytime you want to automate a feature for the user and allow them to download the resulting capture file instead of spending lots of time online. Examples BOOLEAN ss LET ss = SHOWSTAT() SHOWOFF OPENCAP "CAP"+STRING(PCBNODE()),ocFlag IF (ocFlag) THEN DIR "U;NS" CLOSECAP KBDSTUFF "FLAG CAP"+STRING(PCBNODE())+CHR(13) ENDIF IF (ss) THEN SHOWON ELSE SHOWOFF ENDIF See Also CLOSECAP Statement, OPENCAP Statement, SHOWON Statement, SHOWSTAT() Function SHOWON Statement Function Turn on showing information to the display. Syntax SHOWON No arguments are required Remark This statement allows your PPL application to turn on writing information to the local and remote displays. Used in conjunction with the SHOWSTAT() function and the OPENCAP, CLOSECAP, and SHOWOFF statements it allows you to temporarily turn off the display while capturing output to the screen. This can be useful anytime you want to automate a feature for the user and allow them to download the resulting capture file instead of spending lots of time online. Examples BOOLEAN ss LET ss = SHOWSTAT() SHOWOFF OPENCAP "CAP"+STRING(PCBNODE()),ocFlag IF (ocFlag) THEN DIR "U;NS" CLOSECAP KBDSTUFF "FLAG CAP"+STRING(PCBNODE())+CHR(13) ENDIF IF (ss) THEN SHOWON ELSE SHOWOFF ENDIF See Also CLOSECAP Statement, OPENCAP Statement, SHOWOFF Statement, SHOWSTAT() Function SHOWSTAT() Function Function Determine if data is being shown on the display. Syntax SHOWSTAT() No arguments are required Return Type and Value BOOLEAN Returns TRUE if data is being shown on the display, FALSE otherwise. Remarks This function allows your PPL application to determine the status of writing information to the local and remote displays. Used in conjunction with the OPENCAP, CLOSECAP, SHOWON, and SHOWOFF statements it allows you to temporarily turn off the display while capturing output to the screen. This can be useful anytime you want to automate a feature for the user and allow them to download the resulting capture file instead of spending lots of time online. Examples BOOLEAN ss LET ss = SHOWSTAT() SHOWOFF OPENCAP "CAP"+STRING(PCBNODE()),ocFlag IF (ocFlag) THEN DIR "U;NS" CLOSECAP KBDSTUFF "FLAG CAP"+STRING(PCBNODE())+CHR(13) ENDIF IF (ss) THEN SHOWON ELSE SHOWOFF ENDIF See Also CLOSECAP Statement, OPENCAP Statement, SHOWOFF Statement, SHOWON Statement SLPATH() Function Function Return the path of login security files as defined in PCBSetup. Syntax SLPATH() No arguments are required Return Type & Value STRING Returns the path of the PCBoard login security files. Remarks This function will return the path where login security files are located as defined in PCBSetup. It can be used to create and change them on the fly. Examples FAPPEND 1,SLPATH()+STRING(CURSEC),O_WR,S_DB FPUTLN 1,U_NAME() FCLOSE 1 See Also SOUND Statement Function Turn on the speaker on the local computer at a specific frequency. Syntax SOUND freq freq An integer expression with the frequency (in hertz) at which to turn on the speaker or 0 to turn off the speaker. Remarks This statement can be used to generate just about any tone desired on the speaker on the local PC. It has no effect on the remote computer and will only work with the built in speaker (in other words, it has no way of communicating with advanced sound cards). You specify the frequency of the tone you wish to generate in hertz and pass it to the statement, or pass 0 to turn off the speaker. Examples PAGEON FOR i = 1 TO 10 MPRINT CHR(7) SOUND 440 DELAY 9 SOUND 0 DELAY 9 IF (KINKEY() = " ") THEN CHAT GOTO exit ENDIF NEXT :exit See Also SPACE() Function Function Create a string with a specified of spaces. Syntax SPACE(len) len An integer expression with the number of spaces for the new string. Return Type & Value STRING Returns a string of len spaces. Remarks This function is useful when formatting screen displays without ANSI and when writing formatted information out to a file. It will create a string of the length specified with nothing but spaces. The returned string may have anywhere from 0 to 256 spaces. Examples PRINT RANDOM(9),SPACE(5),RANDOM(9),SPACE(5),RANDOM(9) FCREATE 1,"NEWFILE.DAT",O_WR,S_DB FPUTLN 1,"NAME",SPACE(24),"CITY",SPACE(23),"PHONE" FCLOSE 1 See Also SPRINT/SPRINTLN Statements Function Print (write) a line to the local screen (BBS) only (with an optional newline appended). Syntax S P R I N Te x p [ , e x p ] - o r - SPRINTLN [exp[,exp]] exp An expression of any type to evaluate and write to the caller's screen. Remarks These statements will evalutate zero, one or more expressions of any type and write the results to the BBS for the SysOp's display. The SPRINTLN statement will append a newline to the end of the expressions; SPRINT will not. Note that at least one expression must be specified for SPRINT, unlike the SPRINTLN statement which need not have any arguments passed to it. These statements only send information to the local display and do not interpret @ codes; however, complete ANSI sequences will be interpreted. Examples SPRINT "The name of the currently running PPE file is " SPRINTLN PPENAME(),"." SPRINT "The path where it is located is " SPRINTLN PPEPATH(),"." SPRINT "The date is ",DATE()," and the time is ",TIME(),"." SPRINTLN See Also MPRINT/MPRINTLN Statements, PRINT/PRINTLN Statements STACKED Constant Function Set the allow stacked commands flag in an INPUTSTR or PROMPTSTR statement. Value 16 = 10000b = 20o = 10h Remarks The INPUTSTR and PROMPTSTR statements have the ability to allow space and semi-colon characters to be input independent of the valid character string specified. This facilitates entering stacked commands (commands separated by space or semi-colon delimiters) by only requiring a single value be set in the input statement instead of having to add " ;" to every valid character mask. Examples STRING cmds INPUTSTR "Commands",cmds,@X0E,60,MASK_ASCII(),STACKED TOKENIZE cmds LET cmds = GETTOKEN() IF (cmds = "QUIT") END KBDSTUFF cmds+TOKENSTR() See Also INPUTSTR Statement, PROMPTSTR Statement STARTDISP Statement Function Start PCBoard's display routines in a specified mode. Syntax STARTDISP mode mode An integer expression with the mode for display. Remarks PCBoard has two modes for displaying information: non stop and line count. Non stop mode (initiated by passing FNS, for Force Non Stop, as the mode parameter) displays information without regard to how fast the display is or whether or not the user can read it all. Line count mode (initiated by passing FCL, for Force Count Lines, as the mode parameter) displays information while counting lines and pausing after every screenful to wait for user input. Finally, NC may be specified to reinitialize the internal display counters without changing the current mode. Examples STARTDISP FCL FOR i = 1 TO 100 PRINTLN "Line ",i NEXT STARTDISP FNS FOR i = 1 TO 100 PRINTLN "Line ",i NEXT STARTDISP NC FOR i = 1 TO 100 PRINTLN "Line ",i NEXT See Also ABORT() Function, RESETDISP Statement STOP Statement Function Abort PPE execution. Syntax STOP No arguments are required Remarks This statement may be used to abnormally terminate PPE execution at any point. The only real difference between this statement and END is whether or not information written to channel 0 is saved when the . END will save the output to the script answer file; STOP will not. Examples STRING Question, Answer LET Question = "What is your street address ..." GOSUB ask INPUTYN "Save address",Answer,@X0E IF (Answer = NOCHAR()) STOP END :ask ' Sub to ask a question, get an answer, and log them to a file LET Answer = "" PRINTLN "@X0E",Question INPUT "",Answer NEWLINES 2 FPUTLN 0,"Q: ",STRIPATX(Question) FPUTLN 0,"A: ",Answer RETURN See Also END Statement, RETURN Statement STRING Type Function Declare one or more variables of type string. Syntax STRING var|arr(s[,s[,s]])[,var|arr(s[,s[,s]])] var The name of a variable to declare. Must start with a letter [A-Z] which may be followed by letters, digits [0-9] or the underscore [_]. May be of any length but only the first 32 characters are used. arr The name of an array variable to declare. The same naming conventions as var are used. s The size (0-based) of an array variable dimension. Any constant integer expression is allowed. Remarks STRING variables are stored as pointers arrays of characters from 0 to 257 bytes in size. If the array has 0 or 1 characters in it, it is a 0 length string. Arrays with 2 to 257 characters have a length of the array size minus one. Valid string characters are ASCII 1 through ASCII 255. ASCII 0 is reserved for terminating the string and may not appear in the middle of the string. A STRING assignment to an INTEGER will convert the string to the four byte binary integer value (similar to BASIC's VAL function and C's atol function). An INTEGER to STRING assignment will result in a string with the representation of the number (similar to BASIC's STR$ function and C's ltoa function). If a STRING is assigned to or from any other type, an appropriate conversion is performed automatically by PPL. Examples STRING char, str, tmp, labels(10), names(20,3) See Also BOOLEAN Type, DATE Type, INTEGER Type, MONEY Type, TIME Type STRING() Function Function Convert any expression to a string. Syntax STRING(exp) exp Any expression. Return Type & Value STRING Returns exp formatted as a string. Remarks This function is immensely useful anytime you need to convert any expression to string format. For example, to append an integer value to the end of a string without this function, you would need to assign the integer to a string and then append the temporary string to actual string. This is because PPL's normal course of action when performing arithmetic with incompatible types is to convert everything to integer first. With this function, you can accomplish the same function in one line of code with one expression because you are forcing addition of compatible types (strings). Note that PPL does automatically convert incompatible types whenever possible, making this function unnecessary in many cases. This function should only be necessary when trying to append the text representation of a non-string type to a string via the + operator. Examples INTEGER i STRING s(5) FOR i = 1 to 5 LET s(i) = "This is string "+STRING(i) NEXT STRING s LET s = STRING(ABORT())+" "+STRING(DATE())+" "+STRING(10)+" " LET s = s+STRING($10.00)+" "+STRING(TIME()) PRINTLN s ' will print "0 10-31-67 10 $10.00 03:27:00" (or similar) See Also STRIP() Function Function Remove all occurrences of a character from a string. Syntax STRIP(str,ch) str Any string expression. ch String with character to remove from str. Return Type & Value STRING Returns sexp without occurrences of ch that may have been present previously. Remarks This function is used to strip a selected character from a string. This can be useful when you need to remove known formatting characters from a string, such as slashes and hyphens from a date string. Examples STRING s WHILE (LEN(s) < 6) DO INPUTSTR "Enter date (MM-DD- YY)",s,@X0E,8,"0123456789-",DEFS LET s = STRIP(s,"-") ENDWHILE PRINTLN "Date (MMDDYY): ",s See Also STRIPATX() Function Function Remove @X codes from a string. Syntax STRIPATX(sexp) sexp Any string expression. Return Type & Value STRING Returns sexp without any @X codes that may have been present previously. Remarks This function is used to strip PCBoard @X color codes from a string or string expression. This is useful when you want to log information to a file without the @X codes used in the screen display. Examples STRING Question, Answer LET Question = "What is your street address ..." GOSUB ask END :ask ' Sub to ask a question, get an answer, and log them to a file LET Answer = "" PRINTLN "@X0E",Question INPUT "",Answer NEWLINES 2 FPUTLN 0,"Q: ",STRIPATX(Question) FPUTLN 0,"A: ",Answer RETURN See Also SYSOPSEC() Function Function Get the security level as the SysOp security level. Syntax SYSOPSEC() No arguments are required Return Type & Value INTEGER Returns the SysOp security level as defined in PCBSetup. Remarks This function is useful for those occasions when you need to limit functionality in your PPL applications to users having a security level greater than or equal to the defined SysOp security level in PCBSetup. Examples INTEGER min IF (CURSEC() >= SYSOPSEC()) THEN LET min = 60 ELSE LET min = 5 ENDIF ADJTIME min PRINTLN "Your time available has been increased by ",min," minutes" See Also S_DB Constant Function Set the share deny both (read and write) flag in a FCREATE/FOPEN/FAPPEND statement. Value 3 = 11b = 3o = 3h Remarks DOS 3.1 or later (which is what is required by PCBoard) allows processes to decide what mode of file sharing should be allowed. This constant allows you to specify that other processes may not open the same file for either read or write access from the time you open the file to the time you close the file. This is useful when you need exclusive access to a file for any reason and need to restrict other processes access to the same file. Examples FOPEN 1,"FILE.DAT",O_RD,S_DB ' Deny other processes all access FOR i = 1 TO 10 FGET 1,s PRINTLN s NEXT FCLOSE 1 ' Close the file and allow others to open it in any mode See Also S_DN Constant, S_DR Constant, S_DW Constant S_DN Constant Function Set the share deny none flag in a FCREATE/FOPEN/FAPPEND statement. Value 0 = 0b = 0o = 0h Remarks DOS 3.1 or later (which is what is required by PCBoard) allows processes to decide what mode of file sharing should be allowed. This constant allows you to specify that other processes may open the same file for read or write access from the time you open the file to the time you close the file. This is useful when you don't need exclusive access to a file for any reason and need not restrict other processes. Examples FOPEN 1,"FILE.DAT",O_RD,S_DN ' Do not deny other processes any access FOR i = 1 TO 10 FGET 1,s PRINTLN s NEXT FCLOSE 1 ' Close the file and allow others to open it in any mode See Also S_DB Constant, S_DR Constant, S_DW Constant S_DR Constant Function Set the share deny read flag in a FCREATE/FOPEN/FAPPEND statement. Value 1 = 1b = 1o = 1h Remarks DOS 3.1 or later (which is what is required by PCBoard) allows processes to decide what mode of file sharing should be allowed. This constant allows you to specify that other processes may open the same file, but that they may not open it for read access, from the time you open the file to the time you close the file. Examples FOPEN 1,"FILE.DAT",O_RD,S_DR ' Deny other processes read access FOR i = 1 TO 10 FGET 1,s PRINTLN s NEXT FCLOSE 1 ' Close the file and allow others to open it in any mode See Also S_DB Constant, S_DN Constant, S_DW Constant S_DW Constant Function Set the share deny write flag in a FCREATE/FOPEN/FAPPEND statement. Value 2 = 10b = 2o = 2h Remarks DOS 3.1 or later (which is what is required by PCBoard) allows processes to decide what mode of file sharing should be allowed. This constant allows you to specify that other processes may open the same file, but that they may not open it for write access, from the time you open the file to the time you close the file. This is useful when you want to ensure that data will not change while you are reading it. Examples FOPEN 1,"FILE.DAT",O_RD,S_DW ' Deny other processes write access FOR i = 1 TO 10 FGET 1,s PRINTLN s NEXT FCLOSE 1 ' Close the file and allow others to open it in any mode See Also S_DB Constant, S_DN Constant, S_DR Constant TEMPPATH() Function Function Return the path to the temporary work directory as defined in PCBSetup. Syntax TEMPPATH() No arguments are required Return Type & Value STRING Returns the path of the node temporary work files area. Remarks This function will return the path where temporary work files should be created as defined in PCBSetup. This path is a good place for small temporary files that need not be kept permanently since it often points to a RAM drive or other fast local storage. Examples INTEGER rc SHELL TRUE,rc,"DIR",">"+TEMPPATH()+"TMPDIR" DISPFILE TEMPPATH()+"TMPDIR",DEFS DELETE TEMPPATH()+"TMPDIR" See Also TIME Type Function Declare one or more variables of type time. Syntax TIME var|arr(s[,s[,s]])[,var|arr(s[,s[,s]])] var The name of a variable to declare. Must start with a letter [A-Z] which may be followed by letters, digits [0-9] or the underscore [_]. May be of any length but only the first 32 characters are used. arr The name of an array variable to declare. The same naming conventions as var are used. s The size (0-based) of an array variable dimension. Any constant integer expression is allowed. Remarks TIME variables are stored as seconds elapsed since midnight. Valid times are 0 (00:00:00) through 86399 (23:59:59). It is stored internally as a four byte unsigned long integer. If a TIME is assigned to or from an INTEGER type then the seconds since midnight (0-86399) is assigned. If a TIME is assigned to a STRING type then it is automatically converted to the following format: "HH:MM:SS", where HH is the two digit hour (00-23), MM is the two digit minute (00-59), and SS is the two digit second (00-59). If a foreign language is in use that uses a different time format (for example, "HH.MM.SS") then that will be taken into account. If a STRING is assigned to a TIME then PPL will do it's best to convert the string back to the appropriate time. All other types, when assigned to or from a TIME, will be converted to an INTEGER first before being assigned to or from the TIME type. Examples TIME tob, now, pageHours(2), hourList(24) See Also BOOLEAN Type, DATE Type, INTEGER Type, MONEY Type, STRING Type TIME() Function Function Get the current time. Syntax TIME() No arguments are required Return Type & Value TIME Returns the current time. Remarks The time returned is represented internally as the number of seconds elapsed since midnight. It may be used as is (for display, storage or as an argument to another function or statement) or assigned to an integer for arithmetic purposes. 00:00:00 (midnight) has a value of 0, 00:00:01 a value of 1, 00:01:00 a value of 60, 01:00:00 a value of 3600, etc, until 23:59:59 which has a value of 86399. Examples PRINTLN "The time is ",TIME() See Also TIMEAP() Function Function Converts a time value to a 12-hour AM/PM formatted string. Syntax TIMEAP(texp) texp Any time expression. Return Type & Value STRING Returns a string formatted with the time specified by texp in a 12-hour AM/PM format. Remarks TIME values are, by default, formatted for military time ("HH:MM:SS") when displayed or assigned to a string variable. You may wish to format them in a 12-hour AM/PM format in some circumstances, however. This function perform the conversion and format the time in "HH:MM:SS XM" format (HH = hour, MM = minute, SS = second, X = A or P). Examples PRINTLN "The current time is ",TIMEAP(TIME()) See Also TOKCOUNT() Function Function Access the number of tokens pending. Syntax TOKCOUNT() No arguments are required Return Type & Value INTEGER Returns the number of tokens available. Remarks Parameter passing between PCBoard and PPL applications (and between PPL applications) and command line parsing is accomplished via tokens. This function will return the number of tokens available via the GETTOKEN statement and the GETTOKEN() function. The value returned by this will be decremented after each token is retrieved until it reaches 0 (no more tokens available). The TOKENIZE function will overwrite any pending tokens with new tokens and reinitialize this function to the new number. Finally, the TOKENSTR() function will clear this function to 0 and return all tokens in a string with semi-colons separating individual tokens. Examples PRINTLN "There are ",TOKCOUNT()," tokens" WHILE (TOKCOUNT() > 0) PRINTLN GETTOKEN() See Also TOKENIZE Statement Function Split up a string into tokens separated by semi-colons or spaces. Syntax TOKENIZE sexp sexp Any string expression. Remarks One of the strongest features of PCBoard is it's ability to take a series of stacked parameters from a command line and use them all at once instead of requiring the user to navigate a series of menus and select one option at each step of the way. The TOKENIZE statement is the PPL equivalent of what PCBoard uses to break a command line into individual commands (tokens). The number of tokens available may be accessed via the TOKCOUNT() function, and each token may be accessed, one at a time, by the GETTOKEN statement and/or the GETTOKEN() function. Examples STRING cmdline INPUT "Command",cmdline TOKENIZE cmdline PRINTLN "You entered ",TOKCOUNT()," tokens" WHILE (TOKCOUNT() > 0) PRINTLN "Token: ",CHR(34),GETTOKEN(),CHR(34) See Also GETTOKEN Statement, GETTOKEN() Function, TOKCOUNT() Function, TOKENSTR() Function TOKENSTR() Function Function Rebuild and return a previously tokenized string. Syntax TOKENSTR() No arguments are required Return Type & Value STRING Returns the rebuilt string that was previously tokenized. Remarks One of the strongest features of PCBoard is it's ability to take a series of stacked parameters from a command line and use them all at once instead of requiring the user to navigate a series of menus and select one option at each step of the way. The TOKENIZE statement is the PPL equivalent of what PCBoard uses to break a command line into individual commands (tokens). This function will take all pending tokens and build a string with appropriate token separators. For example, the string "R A S" would be broken into three separate tokens; "R", "A" and "S". TOKENSTR() would take those tokens and return the following string: "R;A;S". Note that, regardless of the separator used in the original string, the semi-colon character will be used in the rebuilt string. Examples STRING cmdline INPUT "Command",cmdline TOKENIZE cmdline PRINTLN "You entered ",TOKCOUNT()," tokens" PRINTLN "Original string: ",cmdline PRINTLN " TOKENSTR(): ",TOKENSTR() See Also GETTOKEN Statement, GETTOKEN() Function, TOKCOUNT() Function, TOKENIZE Statement TRIM() Function Function Trim a specified character from both ends of a string. Syntax TRIM(str,ch) str Any string expression. ch A string with the character to strip from both ends of str. Return Type & Value STRING Returns the trimmed str. Remarks A common need in programming is to strip leading and/or trailing spaces (or other characters). This function will strip a specified character from both ends of a string and return the trimmed string. Examples STRING s LET s = " TEST " PRINTLN TRIM(s," ") ' Will print "TEST" PRINTLN TRIM(".....DA"+"TA.....",".") ' Will print "DATA" PRINTLN TRIM(".....DA"+"TA....."," ") ' Will print ".....DATA....." See Also LTRIM() Function, RTRIM() Function TRUE Constant Function To provide a named constant for the boolean true value in boolean expressions. Value 1 = 1b = 1o = 1h Remarks BOOLEAN logic is based on two values: TRUE (1) and FALSE (0). The literal numeric constants 0 and 1 may be used in expressions, or you may use the predefined named constants TRUE and FALSE. They make for more readable, maintainable code and have no more overhead than any other constant value at run time. Examples BOOLEAN flag LET flag = TRUE WHILE (!flag) DO INPUTSTR "Text",s,@X0E,60,"ABCDEFGHIJKLMNOPQRSTUVWXYZ ",UPCASE PRINTLN s IF (s = "QUIT") LET flag = FALSE ENDWHILE See Also FALSE Constant UN_...() Function Function Get a piece of information about a node. Syntax UN_...() No arguments are required UN_ should be followed by one of the following: CITY, NAME, OPER, or STAT. Return Type & Value STRING Returns a string with the desired piece of information. Remarks There are actually four different functions that return information from the USERNET.XXX file. UN_CITY() will return the city field, UN_NAME() will return the user name field, UN_OPER() will return the operation text field, and UN_STAT() will return the status field. The information returned by these functions is only meaningful after executing the RDUNET statement for a specific node. Examples RDUNET PCBNODE() WRUNET PCBNODE(),UN_STAT(),UN_NAME(),UN_CITY(),"Running "+PPENAME(),"" RDUNET 1 WRUNET 1,UN_STAT(),UN_NAME(),UN_CITY(),UN_OPER(),"Hello there node 1" See Also RDUNET Statement, WRUNET Statement UPCASE Constant Function Set the force uppercase flag in an INPUTSTR or PROMPTSTR statement. Value 8 = 1000b = 10o = 8h Remarks The INPUTSTR and PROMPTSTR statements have the ability to force all input characters to uppercase. This is useful in getting case insensitive replies from the user. If this flag is used, you need not pass lowercase valid characters as they will be automatically converted at runtime. If this flag is not used and you need to input alphabetic characters, you should pass both lowercase and uppercase characters in the valid character string. Examples STRING s WHILE (s <> "QUIT") DO INPUTSTR "Text",s,@X0E,60,"ABCDEFGHIJKLMNOPQRSTUVWXYZ ",UPCASE PRINTLN s ENDWHILE See Also INPUTSTR Statement, PROMPTSTR Statement UPPER() Function Function Converts lowercase characters in a string to uppercase. Syntax UPPER(sexp) sexp Any string expression. Return Type & Value STRING Returns sexp with all lowercase characters converted to uppercase. Remarks Although "STRING" is technically different from "string" (ie, the computer doesn't recognize them as being the same because one is uppercase and the other is lowercase), it is often necessary to save, display or compare information in a case insensitive format. This function will return a string with all lowercase characters converted to uppercase. So, using the above example, UPPER("string") would return "STRING". Examples STRING s WHILE (UPPER(s) <> "QUIT") DO INPUT "Text",s PRINTLN LOWER(s) ENDWHILE See Also LOWER() Function U_ADDR() VARIABLE ARRAY Function Allow reading and writing of the current users address information. Type & Value STRING Subscript 0 Address Line 1 (50 characters max). Subscript 1 Address Line 2 (50 characters max). Subscript 2 City (25 characters max). Subscript 3 State (10 characters max). Subscript 4 ZIP Code (10 characters max). Subscript 5 Country (15 characters max). Remarks This array is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that the array is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Additionally, the array will only have meaningful information if the address PSA is installed. The existence of the address PSA may be checked with the PSA() function. Examples IF (PSA(3)) THEN GETUSER INPUT "Addr 1",U_ADDR(0) INPUT "Addr 2",U_ADDR(1) INPUT "City ",U_ADDR(2) INPUT "State ",U_ADDR(3) INPUT "ZIP ",U_ADDR(4) INPUT "Cntry ",U_ADDR(5) PUTUSER ENDIF See Also GETUSER Statement, PSA() Function, PUTUSER Statement U_ALIAS VARIABLE Function Allow reading and writing of the current users alias. Type & Value STRING The current users alias (25 characters max). Remarks This STRING is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Additionally, it will only have meaningful information if the alias PSA is installed. The existence of the alias PSA may be checked with the PSA() function. Examples IF (PSA(1)) THEN GETUSER PRINTLN "Your alias is ",U_ALIAS ELSE PRINTLN "Your name is ",U_NAME() ENDIF See Also GETUSER Statement, PSA() Function, PUTUSER Statement U_BDL() Function Function Access the total number of bytes downloaded by the current user. Syntax U_BDL() No arguments are required Return Type & Value INTEGER Returns the current users total bytes downloaded. Remarks This function will return information that can be useful in modifying PCBoard's built in ratio management system and the view user information command. Of course, it is not limited to that; anywhere you need to know how many bytes the current user has downloaded, this function will provide that information. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples PRINTLN "You have ULed ",U_BUL()," bytes and DLed ",U_BDL()," bytes." See Also U_BDLDAY() Function Function Access the number of bytes downloaded by the current user today. Syntax U_BDLDAY() No arguments are required Return Type & Value INTEGER Returns the current users bytes downloaded today. Remarks This function will return information that can be useful in modifying PCBoard's built in ratio management system and the view user information command. Of course, it is not limited to that; anywhere you need to know how many bytes the current user has downloaded today, this function will provide that information. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples PRINTLN "You have downloaded ",U_BDLDAY()," bytes today." See Also U_BDPHONE VARIABLE Function Allow reading and writing of the current users business/data phone number. Type & Value STRING The current users business/data phone number (13 characters max). Remarks This STRING is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN " Home/Voice Phone Number: ",U_HVPHONE PRINTLN "Business/Data Phone Number: ",U_BDPHONE See Also GETUSER Statement, PUTUSER Statement U_BUL() Function Function Access the total number of bytes uploaded by the current user. Syntax U_BUL() No arguments are required Return Type & Value INTEGER Returns the current users total bytes uploaded. Remarks This function will return information that can be useful in modifying PCBoard's built in ratio management system and the view user information command. Of course, it is not limited to that; anywhere you need to know how many bytes the current user has uploaded, this function will provide that information. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples PRINTLN "You have ULed ",U_BUL()," bytes and DLed ",U_BDL()," bytes." See Also U_CITY VARIABLE Function Allow reading and writing of the current users city information. Type & Value STRING The current users city information (24 characters max). Remarks This STRING is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Note that this information is separate from the address PSA and does not require that the address PSA be installed. Examples GETUSER LET U_CITY = "Timbuktu" PRINTLN "You are now from Timbuktu! :)" PUTUSER See Also GETUSER Statement, PUTUSER Statement U_CLS VARIABLE Function Allow reading and writing of the current users message clear screen flag. Type & Value BOOLEAN The current users clear screen flag status (TRUE or FALSE). Remarks This BOOLEAN is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Turning on the message clear screen flag..." LET U_CLS = TRUE PUTUSER See Also GETUSER Statement, PUTUSER Statement U_CMNT1 VARIABLE Function Allow reading and writing of the current users comment field. Type & Value STRING The current users comment field (30 characters max). Remarks This STRING is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Note that this information is separate from the notes PSA (though similar) and does not require that the notes PSA be installed. Examples GETUSER PRINTLN " User Comment: ",U_CMNT1 PRINTLN "SysOp Comment: ",U_CMNT2 See Also GETUSER Statement, PUTUSER Statement U_CMNT2 VARIABLE Function Allow reading and writing of the current users SysOp comment field. Type & Value STRING The current users SysOp comment field (30 characters max). Remarks This STRING is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Note that this information is separate from the notes PSA (though similar) and does not require that the notes PSA be installed. Examples GETUSER PRINTLN " User Comment: ",U_CMNT1 PRINTLN "SysOp Comment: ",U_CMNT2 See Also GETUSER Statement, PUTUSER Statement U_DEF79 VARIABLE Function Allow reading and writing of the current users message editor default width flag. Type & Value BOOLEAN The current users default editor width flag status (TRUE or FALSE). Remarks This BOOLEAN is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Turning on the wide message editor flag..." LET U_DEF79 = TRUE PUTUSER See Also GETUSER Statement, PUTUSER Statement U_EXPDATE VARIABLE Function Allow reading and writing of the current users subscription expiration date. Type & Value DATE The current users subscription expiration date. Remarks This DATE is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Your subscription will expire on ",U_EXPDATE See Also GETUSER Statement, PUTUSER Statement U_EXPERT VARIABLE Function Allow reading and writing of the current users expert status flag. Type & Value BOOLEAN The current users expert flag status (TRUE or FALSE). Remarks This BOOLEAN is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Turning off expert mode..." LET U_EXPERT = FALSE PUTUSER See Also GETUSER Statement, PUTUSER Statement U_EXPSEC VARIABLE Function Allow reading and writing of the current users expired security level. Type & Value INTEGER The current users security level (0 - 255). Remarks This INTEGER is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Your security after subscription expiration will be ",U_SEC See Also GETUSER Statement, PUTUSER Statement U_FDL() Function Function Access the total number of files downloaded by the current user. Syntax U_FDL() No arguments are required Return Type & Value INTEGER Returns the current users total files downloaded. Remarks This function will return information that can be useful in modifying PCBoard's built in ratio management system and the view user information command. Of course, it is not limited to that; anywhere you need to know how many files the current user has downloaded, this function will provide that information. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples PRINTLN "You have ULed ",U_FUL()," bytes and DLed ",U_FDL()," files." See Also U_FSE VARIABLE Function Allow reading and writing of the current users full screen editor default flag. Type & Value BOOLEAN The current users full screen editor default flag status (TRUE or FALSE). Remarks This BOOLEAN is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Turning on full screen editor as default..." LET U_FSE = TRUE PUTUSER See Also GETUSER Statement, PUTUSER Statement U_FSEP VARIABLE Function Allow reading and writing of the current users full screen editor prompt flag. Type & Value BOOLEAN The current users full screen editor prompt flag status (TRUE or FALSE). Remarks This BOOLEAN is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Turning off full screen editor prompting..." LET U_FSEP = FALSE PUTUSER See Also GETUSER Statement, PUTUSER Statement U_FUL() Function Function Access the total number of files uploaded by the current user. Syntax U_FUL() No arguments are required Return Type & Value INTEGER Returns the current users total files uploaded. Remarks This function will return information that can be useful in modifying PCBoard's built in ratio management system and the view user information command. Of course, it is not limited to that; anywhere you need to know how many files the current user has uploaded, this function will provide that information. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples PRINTLN "You have ULed ",U_FUL()," bytes and DLed ",U_FDL()," files." See Also U_HVPHONE VARIABLE Function Allow reading and writing of the current users home/voice phone number. Type & Value STRING The current users home/voice phone number (13 characters max). Remarks This STRING is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN " Home/Voice Phone Number: ",U_HVPHONE PRINTLN "Business/Data Phone Number: ",U_BDPHONE See Also GETUSER Statement, PUTUSER Statement U_INCONF() Function Function Determine if a user is registered in a conference. Syntax U_INCONF(rec,conf) rec An integer expression with the record number of the user to check. conf An integer expression with the conference number to check. Return Type & Value BOOLEAN Returns TRUE if the user is registered in the specified conference, FALSE otherwise. Remarks It is sometimes necessary to know if a user is registered in a conference (for example, when entering a message to a particular user). This function will return TRUE if the user is registered in the conference specified. Before calling this function you need to find the users record number from the USERS file with the U_RECNUM() function. Examples INTEGER i,rec STRING un,ynStr(1) LET ynStr(0) = "NO" LET ynStr(1) = "YES" INPUT "User name",un NEWLINE LET rec = U_RECNUM(un) FOR i = 1 TO 10 PRINTLN un," in conf ",i,": ",ynStr(U_INCONF(i,rec)) NEXT See Also U_RECNUM() Function U_LDATE() Function Function Access the last log on date of a user. Syntax U_LDATE() No arguments are required Return Type & Value DATE Returns the current users last log on date. Remarks PCBoard tracks the last log on date for each user. This function will return that date for the user currently online. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples PRINTLN "You last logged on ",U_LDATE(),"." See Also U_LDIR() Function Function Access the latest file date found in a file scan by a user. Syntax U_LDIR() No arguments are required Return Type & Value DATE Returns the latest file date found by the current user. Remarks PCBoard tracks the latest file found by each user. This function will return that date for the user currently online. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples PRINTLN "Latest file found was dated ",U_LDIR(),"." See Also U_LOGONS() Function Function Access the total number of system logons by the current user. Syntax U_LOGONS() No arguments are required Return Type & Value INTEGER Returns the current users total system logons. Remarks PCBoard tracks the total number of logons for each user. This function will return that number for the user currently online. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples PRINTLN "You have logged on to @BOARDNAME@ ",U_LOGONS()," times." See Also U_LONGHDR VARIABLE Function Allow reading and writing of the current users long message header flag. Type & Value BOOLEAN The current users long message header flag status (TRUE or FALSE). Remarks This BOOLEAN is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Turning on long message headers..." LET U_LONGHDR = TRUE PUTUSER See Also GETUSER Statement, PUTUSER Statement U_LTIME() Function Function Access the time of day that a user last logged on. Syntax U_LTIME() No arguments are required Return Type & Value TIME Returns the time of day of the current users last log on. Remarks PCBoard tracks the last time of day of the last log on for each user. This function will return that time for the user currently online. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples PRINTLN "You last logged on at ",U_LTIME(),"." See Also U_MSGRD() Function Function Access the total number of messages read by the current user. Syntax U_MSGRD() No arguments are required Return Type & Value INTEGER Returns the current users total messages read. Remarks PCBoard tracks the total number of messages read by each user. This function will return that number for the user currently online. One quick idea for use: a message/file ratio enforcement door. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples IF ((U_MSGRD()+U_MSGWR())/U_FDL() > 10) THEN PRINTLN "You need to do more messaging!!!" END ENDIF See Also U_MSGWR() Function Function Access the total number of messages written by the current user. Syntax U_MSGWR() No arguments are required Return Type & Value INTEGER Returns the current users total messages written. Remarks PCBoard tracks the total number of messages written by each user. This function will return that number for the user currently online. One quick idea for use: a message/file ratio enforcement door. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples IF ((U_MSGRD()+U_MSGWR())/U_FDL() > 10) THEN PRINTLN "You need to do more messaging!!!" END ENDIF See Also U_NAME() Function Function Access the current users name. Syntax U_NAME() No arguments are required Return Type & Value STRING Returns a string with the current users name. Remarks Perhaps the most important piece of information about a caller is his name. The user name differentiates a user from every other user on the BBS and can be used to track PPE user information that must be kept separate from all other users information. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples IF (U_NAME() = "JOHN DOE) THEN PRINTLN "I know who you are! Welcome!" GETUSER LET U_SEC = 110 PUTUSER PRINTLN "Automatically upgraded!" ENDIF See Also U_NOTES() VARIABLE ARRAY Function Allow reading and writing of current user notes. Type & Value STRING Subscript 0-4 SysOp defineable user notes (60 characters max). Remarks This array is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that the array is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Additionally, the array will only have meaningful information if the notes PSA is installed. The existence of the notes PSA may be checked with the PSA() function. Examples INTEGER i IF (PSA(6)) THEN GETUSER FOR i = 0 TO 4 PRINTLN "Note ",i+1,": ",U_NOTES(i) NEXT ENDIF See Also GETUSER Statement, PSA() Function, PUTUSER Statement U_PAGELEN VARIABLE Function Allow reading and writing of the current users page length setting. Type & Value INTEGER The current users page length (0 - 255). Remarks This integer is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Your page length was ",U_PAGELEN LET U_PAGELEN = 20 PRINTLN "Your page length is now ",U_PAGELEN PUTUSER See Also GETUSER Statement, PUTUSER Statement U_PWD VARIABLE Function Allow reading and writing of the current users password. Type & Value STRING The current users password (12 characters max). Remarks This STRING is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. A mask of valid characters that may be used in the U_PWD variable is available via the MASK_PWD function. Examples STRING s INPUT "Enter Password",s,@X0E,12,MASK_PWD(),UPCASE GETUSER IF (s <> U_PWD) THEN PRINTLN "Sorry, hanging up" HANGUP ENDIF See Also GETUSER Statement, MASK_PWD() Function, PUTUSER Statement U_PWDEXP VARIABLE Function Allow reading and writing of the current users password expiration date. Type & Value DATE The current users password expiration date. Remarks This DATE is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Additionally, it will only have meaningful information if the password PSA is installed. The existence of the password PSA may be checked with the PSA() function. Examples IF (PSA(4)) THEN GETUSER PRINTLN U_PWDEXP-DATE()," until current password expiration" LET U_PWDEXP = DATE()+30 PRINTLN "You now have 30 days until you *MUST* change you password." PUTUSER ENDIF See Also GETUSER Statement, PSA() Function, PUTUSER Statement U_PWDHIST() Function Function Access the last three passwords used by the current user. Syntax U_PWDHIST(num) num The number of the password from the history to return (1 through 3). Return Type & Value STRING Returns the specified password from the history (1 for the most recent, 3 for the least recent). Remarks PCBoard has the ability to track the last three passwords used by each user. This function will return one of those passwords from the history for the user currently online. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. However, it does require that the password PSA has been installed to return meaningful information. The existence of the password PSA may be checked via the PSA() function. Examples INTEGER i IF (PSA(4)) THEN FOR i = 1 TO 3 PRINTLN "Password history ",i,": ",U_PWDHIST(i) NEXT ENDIF See Also PSA() Function U_PWDLC() Function Function Access the last date the user changed his password. Syntax U_PWDLC() No arguments are required Return Type & Value DATE Returns the last date the user changed his password. Remarks PCBoard has the ability to track the last date of a password change for each user. This function will return that date for the user currently online. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. However, it does require that the password PSA has been installed to return meaningful information. The existence of the password PSA may be checked via the PSA() function. Examples IF (PSA(4)) PRINTLN "You last changed your password on ",U_PWDLC(),"." See Also PSA() Function U_PWDTC() Function Function Access the number of times the user has changed his password. Syntax U_PWDTC() No arguments are required Return Type & Value INTEGER Returns the number of times the user has changed his password. Remarks PCBoard has the ability to track the total number of times each user changes his password. This function will return that count for the user currently online. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. However, it does require that the password PSA has been installed to return meaningful information. The existence of the password PSA may be checked via the PSA() function. Examples IF (PSA(4)) THEN PRINTLN "You have changed your password ",U_PWDTC()," times." ENDIF See Also PSA() Function U_RECNUM() Function Function Determine if a user is registered on the system and what the record number is. Syntax U_RECNUM(user) user A string expression with the user name to search for. Return Type & Value INTEGER Returns the record number of the user in the USERS file if found or -1 if not found. Remarks This function serves two purposes. The first is to determine whether or not a given user name is registered on the system. If the value -1 is returned the user isn't in the user files. The second use is to get the users record number for the U_INCONF() function to determine whether or not a user is registered in a given conference. Examples INTEGER i,rec STRING un,ynStr(1) LET ynStr(0) = "NO" LET ynStr(1) = "YES" INPUT "User name",un NEWLINE LET rec = U_RECNUM(un) FOR i = 1 TO 10 PRINTLN un," in conf ",i,": ",ynStr(U_INCONF(i,rec)) NEXT See Also U_INCONF() Function U_SCROLL VARIABLE Function Allow reading and writing of the current users multi-screen message scroll flag. Type & Value BOOLEAN The current users scroll flag status (TRUE or FALSE). Remarks This BOOLEAN is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Turning off message scrolling..." LET U_SCROLL = FALSE PUTUSER See Also GETUSER Statement, PUTUSER Statement U_SEC VARIABLE Function Allow reading and writing of the current users security level. Type & Value INTEGER The current users security level (0 - 255). Remarks This INTEGER is set with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is undefined until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Examples GETUSER PRINTLN "Raising your security to level 20..." LET U_SEC = 20 PUTUSER PRINTLN "Automatic upgrade complete!" See Also GETUSER Statement, PUTUSER Statement U_STAT() Function Function Access a statistic about the current user. Syntax U_TIMEON(stat) stat The statistic to retrieve (1 through 15). Return Type & Value DATE Returns the first date the user called the system if stat is 1. INTEGER Returns one of the following for all other values of stat: 2 The number of times the user has paged the SysOp; 3 The number of group chats the user has participated in; 4 The number of comments left by the user; 5 The number of 300 bps connects by the user; 6 The number of 1200 bps connects by the user; 7 The number of 2400 bps connects by the user; 8 The number of connects by the user greater than 2400 bps and less than or equal to 9600 bps (9600 bps >= connect speed > 2400 bps); 9 The number of connects by the user greater than 9600 bps and less than or equal to 14,400 bps (14,400 bps >= connect speed > 9600 bps); 10 The number of security violations by the user; 11 The number of "not registered in conference" warnings to the user; 12 The number of times the user's download limit has been reached; 13 The number of "file not found" warnings to the user; 14 The number of password errors to access the user's account; 15 The number of verify errors to access the user's account. Remarks PCBoard has the ability to track a number of statistics about the user. This function will return the desired statistic for the user currently online. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. However, it does require that the statistics PSA has been installed to return meaningful information. The existence of the statistics PSA may be checked via the PSA() function. Examples STRING label INTEGER i FOPEN 1,PPEPATH()+"STATTEXT",O_RD,S_DN FOR i = 1 TO 15 FGET 1,label PRINTLN label," - ",U_STAT(i) NEXT FCLOSE 1 See Also PSA() Function U_TIMEON() Function Function Access the users time online today in minutes. Syntax U_TIMEON() No arguments are required Return Type & Value INTEGER Returns the users time online today in minutes. Remarks PCBoard tracks the users time online each day. This function will return the elapsed time for the user currently online. Unlike the predefined U_... user variables, this function does not require the use of GETUSER to return valid information. Examples PRINTLN "You have been online for ",U_TIMEON()," total minutes today." See Also U_TRANS VARIABLE Function Allow reading and writing of the current users default transfer protocol letter. Type & Value STRING The current users default transfer protocol letter (1 character max). Remarks This STRING is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Valid characters that may be used in the U_TRANS variable are A through Z and 0 through 9. Examples GETUSER PRINTLN "Your default file transfer protocol letter is ",U_TRANS LET U_TRANS = "N" ' Set to no default protocol PRINTLN "Default file transfer protocol letter set to None" PUTUSER See Also GETUSER Statement, PUTUSER Statement U_VER VARIABLE Function Allow reading and writing of the current users verification string. Type & Value STRING The current users verification string (25 characters max). Remarks This STRING is filled with information from the current users record when the GETUSER statement is executed. It may then be changed and written back to the users record with the PUTUSER statement. Note that it is empty until a GETUSER statement is processed and that changes are not written until a PUTUSER statement is processed. Additionally, it will only have meaningful information if the verification PSA is installed. The existence of the verification PSA may be checked with the PSA() function. Examples STRING s IF (PSA(2)) THEN GETUSER PRINTLN "Enter verification information" INPUT "",s IF (s <> U_VER) HANGUP ELSE PRINTLN "No verification information available" ENDIF See Also GETUSER Statement, PSA() Function, PUTUSER Statement VALCC() Function Function Tests a string for credit card number format validity. Syntax VALCC(sexp) sexp Any string expression. Return Type & Value BOOLEAN Returns TRUE if the string is a valid credit card number format, FALSE otherwise. Remarks This function will take a string and attempt to identify it as a credit card number. If the number is invalid for any reason (insufficient digits or bad checksum, primarily) then this function will return FALSE, otherwise it will return TRUE. Examples STRING s WHILE (!VALCC(s)) DO INPUT "CC #",s NEWLINES 2 ENDWHILE PRINTLN CCTYPE(s)," - ",FMTCC(s) See Also CCTYPE() Function, FMTCC() Function, VALDATE() Function, VALTIME() Function VALDATE() Function Function Tests a string for date format validity. Syntax VALDATE(sexp) sexp Any string expression. Return Type & Value BOOLEAN Returns TRUE if the string is a valid date format, FALSE otherwise. Remarks PPL does it best to convert incompatible types, as needed, automatically. Converting a STRING type to a DATE type is particularly problematic because of the virtually unlimited numbers of strings possible. This function checks to make sure that the hour is from 0 to 23, the minute is from 0 to 59, and the second (optional) is from 0 to 59. Also, each field (hours/minutes/seconds) must be separated by a colon. If the string matches these requirements then the string is considered valid and TRUE is returned. Any other string will result in a FALSE value being returned. Examples STRING s WHILE (!VALTIME(s)) DO INPUT "Time",s NEWLINES 2 ENDWHILE TIME t LET t = s PRINTLN s," ",t See Also VALCC() Function, VALDATE() Function VALTIME() Function Function Tests a string for time format validity. Syntax VALTIME(sexp) sexp Any string expression. Return Type & Value BOOLEAN Returns TRUE if the string is a valid time format, FALSE otherwise. Remarks PPL does it best to convert incompatible types, as needed, automatically. Converting a STRING type to a TIME type is particularly problematic because of the virtually unlimited numbers of strings possible. This function checks to make sure that the hour is from 0 to 23, the minute is from 0 to 59, and the second (optional) is from 0 to 59. Also, each field (hours/minutes/seconds) must be separated by a colon. If the string matches these requirements then the string is considered valid and TRUE is returned. Any other string will result in a FALSE value being returned. Examples STRING s WHILE (!VALTIME(s)) DO INPUT "Time",s NEWLINES 2 ENDWHILE TIME t LET t = s PRINTLN s," ",t See Also VALCC() Function, VALDATE() Function VARADDR Statement Function Sets a variable to the complete address of another variable. Syntax VARADDR src,dest src The variable to get the address of. dest The variable to store the address in. Remarks This statement is primarily useful in conjunction with the DOINTR statement. It may be necessary to give an interrupt the address of a memory location that can be used to store information. This statement will allow you to get the address of a specified variable to pass to the DOINTR statement. Examples ' Create subdirectory - DOS function 39h INTEGER addr STRING path LET path = "C:\$TMPDIR$" VARADDR path,addr DOINTR 21h,39h,0,0,addr%10000h,0,0,0,addr/10000h,0 IF (REGCF() & (REGAX() = 3)) THEN PRINTLN "Error: Path not found" ELSE IF (REGCF() & (REGAX() = 5)) THEN PRINTLN "Error: Access Denied" ELSE IF (REGCF()) THEN PRINTLN "Error: Unknown Error" ELSE PRINTLN "Directory successfully created..." ENDIF See Also MKADDR() Function, VAROFF Statement, VARSEG Statement VAROFF Statement Function Sets a variable to the offset address of another variable. Syntax VAROFF src,dest src The variable to get the offset address of. dest The variable to store the offset address in. Remarks This statement is primarily useful in conjunction with the DOINTR statement. It may be necessary to give an interrupt the address of a memory location that can be used to store information. This statement will allow you to get the offset address of a specified variable to pass to the DOINTR statement. Examples ' Create subdirectory - DOS function 39h INTEGER saddr, oaddr STRING path LET path = "C:\$TMPDIR$" VARSEG path,saddr VAROFF path,oaddr DOINTR 21h,39h,0,0,oaddr,0,0,0,saddr,0 IF (REGCF() & (REGAX() = 3)) THEN PRINTLN "Error: Path not found" ELSE IF (REGCF() & (REGAX() = 5)) THEN PRINTLN "Error: Access Denied" ELSE IF (REGCF()) THEN PRINTLN "Error: Unknown Error" ELSE PRINTLN "Directory successfully created..." ENDIF See Also MKADDR() Function, VARADDR Statement, VARSEG Statement VARSEG Statement Function Sets a variable to the segment address of another variable. Syntax VARSEG src,dest src The variable to get the segment address of. dest The variable to store the segment address in. Remarks This statement is primarily useful in conjunction with the DOINTR statement. It may be necessary to give an interrupt the address of a memory location that can be used to store information. This statement will allow you to get the segment address of a specified variable to pass to the DOINTR statement. Examples ' Create subdirectory - DOS function 39h INTEGER saddr, oaddr STRING path LET path = "C:\$TMPDIR$" VARSEG path,saddr VAROFF path,oaddr DOINTR 21h,39h,0,0,oaddr,0,0,0,saddr,0 IF (REGCF() & (REGAX() = 3)) THEN PRINTLN "Error: Path not found" ELSE IF (REGCF() & (REGAX() = 5)) THEN PRINTLN "Error: Access Denied" ELSE IF (REGCF()) THEN PRINTLN "Error: Unknown Error" ELSE PRINTLN "Directory successfully created..." ENDIF See Also MKADDR() Function, VARADDR Statement, VAROFF Statement VER() Function Function Get the version of PPL available. Syntax VER() No arguments are required Return Type & Value INTEGER Returns the version number of PPL running. Remarks As time passes, new features will be added to PCBoard and PPL. Of course, in order to utilize the new features, you must be running a version of PCBoard that supports them. This function will return the version of PCBoard (and PPL). For PCBoard version 15.0 this value will be 1500. In other words, the major version will be accessable via VER()/100, and the minor version will be available via VER()%100. Everything documented herein will be available for all versions greater than or equal to 1500. Future PPL features will be documented with the required version. Examples IF (VER() < 1600) THEN PRINTLN "PCBoard Version 16.0 required for this PPE file" END ENDIF FOO a,b,c,d,e ' Obviously, this is not a 15.0 statement See Also WAIT Statement Function Wait for the user to hit ENTER. Syntax WAIT No arguments are required Remarks It is often necessary to pause in the display of information and wait for the user to catch up. This statement allows you to wait for the user to hit ENTER before continuing. It displays prompt number 418 from the PCBTEXT file for the current language to let the user know what is expected. Examples PRINTLN "Your account has expired!" PRINTLN "You are about to be logged off" WAIT See Also MORE Statement WAITFOR Statement Function Wait for a specific string of text to come in from the modem. Syntax WAITFOR str,flag,sec str Any string expression. flag A variable to return the status. sec An integer expression with the maximum number of seconds to wait. Remarks This statement can be used to wait for specific replies to questions, responses from terminal emulators and modem result codes. If the text that is needed isn't received within the specified time period, or if there is not a remote caller online, flag will be set to FALSE. If the text is found, then flag will be TRUE. If a remote caller is online this statement will wait up to the maximum time for the text and return TRUE or FALSE as appropriate. If the caller is local, it will immediately return FALSE. Also, the text to wait for is not case sensitive. "connect" will match "CONNECT". Examples BOOLEAN flag KBDCHKOFF CDCHKOFF DTROFF DELAY 18 DTRON SENDMODEM "ATDT5551212" ' Please don't really dial this number! WAITFOR "CONNECT",flag,60 IF (!flag) SPRINLN "No connect found in 60 seconds" CDCHKON KBDCHKON See Also WHILE/ENDWHILE Statement Function Execute one or more statments while a condition is true. Syntax W H I L E ( b e x p ) s t a t e m e n t - o r - W H I L E ( b e x p ) D O s t a t e m e n t ( s ) ENDWHLLE bexp Any boolean expression. statement Any valid PPL statement. Remarks Computers are known for their ability to perform monotonous tasks quickly, efficiently, and accurately. What better way to implement monotony than through a WHILE loop? The WHILE statement supports two types of loops: logical and block. A logical WHILE loop is a single statement; if a condition is TRUE, execute a single statement and check again. A block WHILE loop can be one or more statements. The start of a block WHILE loop is differentiated from a logical WHILE loop by the DO keyword immediately after the condition. At some point in the loop some action must be taken that will make the condition FALSE. If the condition never changes from TRUE to FALSE you have what is known as an infinite loop; your computer will appear to be hung, even though it is rapidly executing things just as fast as it can. Be sure to thoroughly test all programs, but especially programs with loops! Examples INTEGER i LET i = 0 WHILE (i < 10) GOSUB sub END :sub PRINTLN "i is ",i INC i RETURN INTEGER i LET i = 0 WHILE (i < 10) DO PRINTLN "i is ",i INC i ENDWHILE See Also FOR/NEXT Statement, IF/ELSEIF/ELSE/ENDIF Statement WORDWRAP Constant Function Set the word wrap flag in an INPUTSTR or PROMPTSTR statement. Value 512 = 1000000000b = 1000o = 200h Remarks The INPUTSTR and PROMPTSTR statements have the ability to word wrap from one input statement to the next input statement. If you reach the end of the input field PCBoard will automatically save the last word from the input field in an internal buffer. The next input statement will use that saved word if both statements used the WORDWRAP constant. If the passed variable isn't empty or if an input statement is used that doesn't have the WORDWRAP flag set then the saved word will not be used. Examples STRING s(5) INTEGER i CLS FOR i = 1 TO 5 INPUTSTR "Line "+STRING(i),s(i),@X0E,40,MASK_ASCII(),WORDWRAP+NEWL INE NEXT CLS FOR i = 1 TO 5 PRINTLN "Line ",i,": ",s(i) NEXT See Also INPUTSTR Statement, PROMPTSTR Statement WRUNET Statement Function Write information to the USERNET file for a specific node. Syntax WRUNET node,stat,name,city,oper,br node An integer expression with the node to update. stat A string expression with the new node status. name A string expression with the new node user name. city A string expression with the new node city. oper A string expression with the new node operation text. br A string expression with the new node broadcast text. Remarks To facilitate internode communications, a file named USERNET.XXX is maintained with an entry for each node on the system. This file is used by the BROADCAST command of PCBoard and to prevent multiple simultaneous logins, among other things. This statement may be used to change information for the current node (for example, to update operation text during PPE execution) or other nodes (for example, to broadcast a message). Examples RDUNET PCBNODE() WRUNET PCBNODE(),UN_STAT(),UN_NAME(),UN_CITY(),"Running "+PPENAME(),"" RDUNET 1 WRUNET 1,UN_STAT(),UN_NAME(),UN_CITY(),UN_OPER(),"Hello there node 1" See Also RDUNET Statement, UN_...() Function WRUSYS Statement Function Write a USERS.SYS file out to disk. Syntax WRUSYS No arguments are required Remarks Some DOOR applications require a USERS.SYS file to access information about the caller. This statement allows you to create that file prior to running an application via the SHELL statement. Should the DOOR make changes to the USERS.SYS file, you should use the RDUSYS statement after the SHELL to read the changes back into memory. It should be noted that it is not possible to create the USERS.SYS file with a TPA record with this statement. Examples INTEGER ret WRUSYS SHELL FALSE,ret,"MYAPP.EXE","" RDUSYS See Also RDUSYS Statement XOR() Function Function Calculate the bitwise XOR (exclusive or) of two integer arguments. Syntax AND(iexp1,iexp2) iexp1 Any integer expression. iexp2 Any integer expression. Return Type & Value INTEGER Returns the bitwise XOR of iexp1 and iexp2. Remarks This function may be used to toggle selected bits in an integer expression by XORing the expression with a mask that has the bits to toggle set to 1 and the bits to ignore set to 0. Examples ' Toggle the bits in the low byte PRINTLN XOR(1248h,00FFh) ' Toggle a flag INTEGER flag LET flag = XOR(flag,1) See Also AND() Function, NOT() Function, OR() Function YEAR() Function Function Extracts the year from a specified date. Syntax YEAR(dexp) dexp Any date expression. Return Type & Value INTEGER Returns the year from the specified date expression (dexp). Valid return values are from 1900 to 2079. Remarks This function allows you to extract a particular piece of information about a DATE value, in this case the year of the date. Examples PRINTLN "This year is: ",YEAR(DATE()) See Also DAY() Function, DOW() Function, MONTH() Function YESCHAR() Function Function Get the yes response character for the current language. Syntax YESCHAR() No arguments are required Return Type & Value STRING Returns the yes character for the current language. Remarks Support for foreign language yes/no responses can be easily added by using this function to determine what an affirmative response should be instead of hardcoding the english "Y" character. Examples STRING ans LET ans = YESCHAR() INPUTSTR "Run program now",ans,@X0E,1,"",AUTO+YESNO IF (ans = NOCHAR()) END See Also NOCHAR() Function, YESNO Constant YESNO Constant Function Set the international yes/no response flag in an INPUTSTR or PROMPTSTR statement. Value 16384 = 100000000000000b = 40000o = 4000h Remarks The INPUTSTR and PROMPTSTR statements have the ability to allow a yes/no response to be entered in addition to any valid characters passed to the statement. The extra characters allowed are Y/N (or whatever characters were defined for the current language; spanish would use S/N, french would use O/N, etc). Note that you do not need to pass any valid characters to use this flag; regardless of the other legal characters the international Y/N characters will be allowed. Examples STRING ans LET ans = NOCHAR() INPUTSTR "Run program now",ans,@X0E,1,"",AUTO+YESNO IF (ans = NOCHAR()) END See Also INPUTSTR Statement, NOCHAR() Function, PROMPTSTR Statement, YESCHAR() Function